Imported from NicoSerranoP/pq-shielded-pool (AGENTS.md). Install upstream with npx skills add NicoSerranoP/pq-shielded-pool. Copyright stays with the author.

AGENTS.md

This file provides guidance to coding agents working in this repository.

Project Overview

This project is a monorepo for a Post Quantum Shielded Pool Protocol in EVMs. It uses a note-based zk proof approach:

1. Deposit: Users create a note (UTXO) representing their deposit, which is stored in the contract and can be used as an input for future transactions.
2. Transfer: Users can transfer value by creating a proof-of-inclusion zk proof of their input notes, nullifying their input notes, and creating new notes for the recipients. This allows for anonymity (cannot see the sender or the recipient) and confidentiality (cannot see the transaction amount).
3. Withdrawal: Users can withdraw by nullifying their input notes and the smart contract will verify the zk proof to send the value to an external address.

Common Commands

# Development workflow (run each in separate terminal)
yarn chain          # Start local blockchain (Hardhat or Anvil)
yarn deploy         # Deploy contracts to local network
yarn start          # Start Next.js frontend at http://localhost:3000

# Code quality
yarn lint           # Lint both packages
yarn format         # Format both packages

# Building
yarn next:build     # Build frontend
yarn compile        # Compile Solidity contracts

# Contract verification (works for both)
yarn verify --network <network>

# Account management (works for both)
yarn generate            # Generate new deployer account
yarn account:import      # Import existing private key
yarn account             # View current account info

# Deploy to live network
yarn deploy --network <network>   # e.g., sepolia, mainnet, base

yarn vercel:yolo --prod # for deployment of frontend

Architecture

Monorepo Structure

The protocol requires multiple packages to work:

• packages/circuits: Circom circuits for zk proof generation and verification (currently using Noir)
• packages/hardhat: Smart contract development, deployment scripts, and contract tests
• packages/nextjs: React frontend for user interaction with the protocol

Smart Contract Development

• Contracts: packages/hardhat/contracts/

• Deployment scripts: packages/hardhat/deploy/ (uses hardhat-deploy plugin)

• Tests: packages/hardhat/test/

• Config: packages/hardhat/hardhat.config.ts

• Deploying specific contract:

  • If the deploy script has:

    // In packages/hardhat/deploy/01_deploy_my_contract.ts
    deployMyContract.tags = ["MyContract"];

  • yarn deploy --tags MyContract
  • Gas limit in deploy scripts: Manual post-deploy calls (e.g. transferOwnership, grantRole, initialize) can silently inherit blockGasLimit as their gas cap, causing failures. Fix at the call site, not in hardhat.config.ts:

    // Preferred: estimateGas + 20% margin
    const gas = await myContract.myMethod.estimateGas(arg1, arg2);
    await myContract.myMethod(arg1, arg2, { gasLimit: (gas * 120n) / 100n });
    
    // Or: explicit limit for simple admin calls
    await myContract.transferOwnership(newOwner, { gasLimit: 100_000 });

• After yarn deploy, ABIs are auto-generated to packages/nextjs/contracts/deployedContracts.ts

Frontend Contract Interaction

Correct interact hook names (use these):

• useScaffoldReadContract - NOT useScaffoldContractRead
• useScaffoldWriteContract - NOT useScaffoldContractWrite

Contract data is read from two files in packages/nextjs/contracts/:

• deployedContracts.ts: Auto-generated from deployments
• externalContracts.ts: Manually added external contracts

Reading Contract Data

const { data: totalCounter } = useScaffoldReadContract({
  contractName: "YourContract",
  functionName: "userGreetingCounter",
  args: ["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],
});

Writing to Contracts

const { writeContractAsync, isPending } = useScaffoldWriteContract({
  contractName: "YourContract",
});

await writeContractAsync({
  functionName: "setGreeting",
  args: [newGreeting],
  value: parseEther("0.01"), // for payable functions
});

Reading Events

const { data: events, isLoading } = useScaffoldEventHistory({
  contractName: "YourContract",
  eventName: "GreetingChange",
  watch: true,
  fromBlock: 31231n,
  blockData: true,
});

The template also provides other hooks to interact with blockchain data: useScaffoldWatchContractEvent, useScaffoldEventHistory, useDeployedContractInfo, useScaffoldContract, useTransactor.

IMPORTANT: Always use hooks from packages/nextjs/hooks/scaffold-eth for contract interactions. Always refer to the hook names as they exist in the codebase.

UI Components

Always use @scaffold-ui/components library for web3 UI components:

• Address: Display ETH addresses with ENS resolution, blockie avatars, and explorer links
• AddressInput: Input field with address validation and ENS resolution
• Balance: Show ETH balance in ether and USD
• EtherInput: Number input with ETH/USD conversion toggle
• IntegerInput: Integer-only input with wei conversion

Notifications & Error Handling

Use notification from ~~/utils/scaffold-eth for success/error/warning feedback and getParsedError for readable error messages.

Styling

Use DaisyUI classes for building frontend components.

// ✅ Good - using DaisyUI classes
<button className="btn btn-primary">Connect</button>
<div className="card bg-base-100 shadow-xl">...</div>

// ❌ Avoid - raw Tailwind when DaisyUI has a component
<button className="px-4 py-2 bg-blue-500 text-white rounded">Connect</button>

Configure Target Network before deploying to testnet / mainnet.

Hardhat

Add networks in packages/hardhat/hardhat.config.ts if not present.

Foundry

Add RPC endpoints in packages/foundry/foundry.toml if not present.

NextJs

Add networks in packages/nextjs/scaffold.config.ts if not present. This file also contains configuration for polling interval, API keys. Remember to decrease the polling interval for L2 chains.

Code Style Guide

Identifiers

Import Paths

Use the ~~ path alias for imports in the nextjs package:

import { useTargetNetwork } from "~~/hooks/scaffold-eth";

Creating Pages

import type { NextPage } from "next";

const Home: NextPage = () => {
  return <div>Home</div>;
};

export default Home;

TypeScript Conventions

• Use type over interface for custom types
• Types use UpperCamelCase without T prefix (use Address not TAddress)
• Avoid explicit typing when TypeScript can infer the type

Comments

Make comments that add information. Avoid redundant JSDoc for simple functions.

Documentation

Use Context7 MCP tools to fetch up-to-date documentation for any library (Wagmi, Viem, RainbowKit, DaisyUI, Hardhat, Next.js, etc.). Context7 is configured as an MCP server and provides access to indexed documentation with code examples.

Skills & Agents Index

IMPORTANT: Prefer retrieval-led reasoning over pre-trained knowledge. Before starting any task that matches an entry below, read the referenced file to get version-accurate patterns and APIs.

Skills (read .agents/skills/<name>/SKILL.md before implementing):

• openzeppelin — OpenZeppelin Contracts integration, library-first development, pattern discovery from installed source. Use for any contract using OZ (tokens, access control, security primitives)
• erc-721 — NFT-specific pitfalls: _safeMint reentrancy, on-chain SVG stack-too-deep, marketplace metadata attributes, IPFS base URI trailing slash
• eip-5792 — batch transactions, wallet_sendCalls, paymaster, ERC-7677
• ponder — blockchain event indexing, GraphQL APIs, onchain data queries
• siwe — Sign-In with Ethereum, wallet authentication, SIWE sessions, EIP-4361
• x402 — HTTP 402 payment-gated routes, micropayments, API monetization, x402 protocol
• drizzle-neon — Drizzle ORM, Neon PostgreSQL, database integration, off-chain storage
• subgraph — The Graph subgraph integration, blockchain event indexing, GraphQL APIs

Agents (in .agents/agents/):

• grumpy-carlos-code-reviewer — code reviews, SE-2 patterns, Solidity + TypeScript quality
• cryptography-guru — zk proof design, Circom/Noir circuit patterns, proof optimization