Imported from clawdbotatg/clawdviction (AGENTS.md). Install upstream with npx skills add clawdbotatg/clawdviction. Copyright stays with the author.

AGENTS.md

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

⚠️ DEPLOYMENT — READ THIS FIRST

ClawdViction deploys to the BuidlGuidl DAO Vercel account, NOT clawdbotatg's personal account.

• Production URL: https://clawdviction.vercel.app
• Vercel team: buidlguidldao (teamId: team_CGnKjJxxZopM4R0pQR8RsBSP)
• Vercel project: clawdviction (projectId: prj_Fov9vI9JKInQDviTGdxg0xjOnuPX)
• Deploy method: Push to main branch → GitHub auto-triggers Vercel deploy. Do NOT use Vercel CLI.
• Wrong project: prj_FasE5ieSoP6Ah9go4NkJ1utO7wHe is a different project — ignore it.

AI / LLM

• All AI routes use Venice AI (OpenAI-compatible) — NOT Anthropic directly
• Model: zai-org-glm-5
• Env var: VENICE_API_KEY (value starts with VENICE_INFERENCE_KEY_...)
• Base URL: https://api.venice.ai/api/v1
• Always set venice_parameters: { include_venice_system_prompt: false, strip_thinking_response: true }
• GLM 5 uses chain-of-thought reasoning — strip_thinking_response: true is required or content will be empty

Project Overview

Scaffold-ETH 2 (SE-2) is a starter kit for building dApps on Ethereum. It comes in two flavors based on the Solidity framework:

• Hardhat flavor: Uses packages/hardhat with hardhat-deploy plugin
• Foundry flavor: Uses packages/foundry with Forge scripts

Both flavors share the same frontend package:

• packages/nextjs: React frontend (Next.js App Router, not Pages Router, RainbowKit, Wagmi, Viem, TypeScript, Tailwind CSS with DaisyUI)

Detecting Which Flavor You're Using

Check which package exists in the repository:

• If packages/hardhat exists → Hardhat flavor (follow Hardhat instructions)
• If packages/foundry exists → Foundry flavor (follow Foundry instructions)

Common Commands

Commands work the same for both flavors unless noted otherwise:

# 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

Smart Contract Development

Hardhat Flavor

• 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

Foundry Flavor

• Contracts: packages/foundry/contracts/
• Deployment scripts: packages/foundry/script/ (uses custom deployment strategy)
  • Example: packages/foundry/script/Deploy.s.sol and packages/foundry/script/DeployYourContract.s.sol
• Tests: packages/foundry/test/
• Config: packages/foundry/foundry.toml
• Deploying a specific contract:
  • Create a separate deployment script and run yarn deploy --file DeployYourContract.s.sol

Both Flavors

• 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,
});

SE-2 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

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.

Specialized Agents

Use these specialized agents for specific tasks:

• grumpy-carlos-code-reviewer: Use this agent for code reviews before finalizing changes