diff --git a/docs/deploying-smart-contracts-with-foundry.md b/docs/deploying-smart-contracts-with-foundry.md new file mode 100644 index 0000000..2c17bfe --- /dev/null +++ b/docs/deploying-smart-contracts-with-foundry.md @@ -0,0 +1,41 @@ +# Deploying Smart Contracts on Arc Testnet with Foundry + +This guide walks through writing, testing, and deploying Solidity smart contracts on Arc Testnet using Foundry. + +## Network Configuration + +| Parameter | Value | +|-----------|-------| +| RPC URL | https://rpc.testnet.arc.network | +| Chain ID | 5042002 | +| Gas Token | USDC | +| Explorer | https://testnet.arcscan.app | + +## Installing Foundry + +```bash +curl -L https://foundry.paradigm.xyz | bash +source ~/.bashrc +foundryup +``` + +## Creating a Project + +```bash +forge init my-arc-project && cd my-arc-project +``` + +## Deploying to Arc Testnet + +```bash +forge create src/HelloArc.sol:HelloArc \ + --rpc-url https://rpc.testnet.arc.network \ + --private-key YOUR_PRIVATE_KEY \ + --broadcast +``` + +## Resources + +- [Arc Docs](https://docs.arc.network) +- [Foundry Book](https://book.getfoundry.sh) +- [Explorer](https://testnet.arcscan.app) diff --git a/docs/examples/arc-intelligence-dashboard.md b/docs/examples/arc-intelligence-dashboard.md new file mode 100644 index 0000000..a269008 --- /dev/null +++ b/docs/examples/arc-intelligence-dashboard.md @@ -0,0 +1,56 @@ +# Arc Intelligence Dashboard + +A real-time Next.js dashboard for Arc Testnet that visualizes X402 payments, ERC-8004 agent identity, ERC-8183 jobs, and deployed contracts. + +## Live Demo + +https://arc-intelligence-dashboard.vercel.app + +## Features + +- Real-time USDC balance (refreshed every 10 seconds) +- Live Arc Testnet block number +- Transaction count for main agent address +- Agentic Stack status (X402, ERC-8004, ERC-8183) +- 15 deployed Solidity contracts with explorer links +- circlefin/arc-node contribution history + +## Tech Stack + +- Next.js 16 with TypeScript +- Tailwind CSS +- viem for Arc Testnet RPC +- Deployed on Vercel + +## Quick Start + +npm install +npm run dev + +## Arc Testnet Configuration + +const arcTestnet = { + id: 5042002, + name: "Arc Testnet", + rpcUrls: { default: { http: ["https://rpc.testnet.arc.network"] } }, + blockExplorers: { default: { name: "Arcscan", url: "https://testnet.arcscan.app" } }, +}; + +## Data Fetching + +The dashboard uses viem createPublicClient to fetch: +- ERC-20 USDC balance via balanceOf() +- Latest block number via getBlockNumber() +- Transaction count via getTransactionCount() + +All three queries run concurrently with Promise.all and refresh every 10 seconds. + +## GitHub Repository + +https://github.com/consumeobeydie/arc-intelligence-dashboard + +## Resources + +- Arc Docs: https://docs.arc.network +- Arc Testnet Explorer: https://testnet.arcscan.app +- viem: https://viem.sh diff --git a/docs/examples/arc-mcp-server.md b/docs/examples/arc-mcp-server.md new file mode 100644 index 0000000..61b9fcc --- /dev/null +++ b/docs/examples/arc-mcp-server.md @@ -0,0 +1,62 @@ +# Arc MCP Server + +A Model Context Protocol (MCP) server that gives AI tools like Claude Code direct access to Arc Testnet blockchain data. + +## What is MCP? + +Model Context Protocol (MCP) is an open standard that lets AI tools discover and use external tools and data sources. With this Arc MCP server, Claude Code can query Arc Testnet directly during conversations. + +## Available Tools + +| Tool | Description | +|------|-------------| +| get_balance | Get USDC balance for any address | +| get_transaction | Get transaction details by hash | +| get_block | Get latest block information | +| get_tx_count | Get transaction count for an address | +| get_agent_info | Get ERC-8004 agent information | +| get_job_status | Get ERC-8183 job status | +| get_network_info | Get network info and contract addresses | + +## Installation + +git clone https://github.com/consumeobeydie/arc-mcp-server.git +cd arc-mcp-server +npm install + +## Add to Claude Code + +claude mcp add --transport stdio arc-testnet node /path/to/arc-mcp-server/src/index.js + +## Example Usage + +Once added, ask Claude Code: +- "Get the USDC balance of 0x54b4B44749a95070560509B6Ec0be501665CcF63" +- "Get Arc Testnet network info" +- "Get ERC-8004 agent info" +- "Get status of job 110935" + +## Example Output + +Claude Code returns structured data like: + +Network: Arc Testnet +Chain ID: 5042002 +Gas Token: USDC +Finality: Sub-second deterministic +Latest Block: 46,336,076 + +Contracts: +- USDC: 0x3600000000000000000000000000000000000000 +- IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e +- AgenticCommerce: 0x0747EEf0706327138c69792bF28Cd525089e4583 + +## GitHub Repository + +https://github.com/consumeobeydie/arc-mcp-server + +## Resources + +- Arc MCP Docs: https://docs.arc.io/ai/mcp +- Model Context Protocol: https://modelcontextprotocol.io +- Arc Testnet Explorer: https://testnet.arcscan.app diff --git a/docs/examples/erc8004-agent-registration.md b/docs/examples/erc8004-agent-registration.md new file mode 100644 index 0000000..b1e5c2d --- /dev/null +++ b/docs/examples/erc8004-agent-registration.md @@ -0,0 +1,180 @@ +# ERC-8004 AI Agent Registration on Arc Testnet + +This example shows how to register an AI agent with onchain identity, build reputation, and verify credentials using the ERC-8004 standard on Arc Testnet with Circle Developer-Controlled Wallets. + +## Overview + +ERC-8004 provides onchain identity and reputation for AI agents. Combined with x402 payments, it enables fully autonomous agents that can prove their identity, build trust, and transact on Arc Testnet. + +## ERC-8004 Contracts on Arc Testnet + +| Contract | Address | +|----------|---------| +| IdentityRegistry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | +| ReputationRegistry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` | +| ValidationRegistry | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` | + +## Prerequisites + +- Node.js v22+ +- Circle Developer Console account with API key +- Entity Secret registered in Circle Console + +## Installation + +```bash +mkdir arc-erc8004-agent && cd arc-erc8004-agent +npm init -y +npm install @circle-fin/developer-controlled-wallets viem dotenv +``` + +## Environment Setup + +```bash +# .env +CIRCLE_API_KEY=your_circle_api_key +CIRCLE_ENTITY_SECRET=your_entity_secret +``` + +## Complete Implementation + +```javascript +const { initiateDeveloperControlledWalletsClient } = require("@circle-fin/developer-controlled-wallets"); +const { createPublicClient, http, parseAbiItem, keccak256, toHex } = require("viem"); +require("dotenv").config(); + +const arcTestnet = { + id: 5042002, + name: "Arc Testnet", + nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 18 }, + rpcUrls: { default: { http: ["https://rpc.testnet.arc.network"] } }, + blockExplorers: { default: { name: "Arcscan", url: "https://testnet.arcscan.app" } }, + testnet: true, +}; + +const IDENTITY_REGISTRY = "0x8004A818BFB912233c491871b3d84c89A494BD9e"; +const REPUTATION_REGISTRY = "0x8004B663056A597Dffe9eCcC1965A193B7388713"; +const VALIDATION_REGISTRY = "0x8004Cb1BF31DAf7788923b405b754f57acEB4272"; +const METADATA_URI = "ipfs://bafkreibdi6623n3xpf7ymk62ckb4bo75o3qemwkpfvp5i25j66itxvsoei"; + +const circleClient = initiateDeveloperControlledWalletsClient({ + apiKey: process.env.CIRCLE_API_KEY, + entitySecret: process.env.CIRCLE_ENTITY_SECRET, +}); + +const publicClient = createPublicClient({ + chain: arcTestnet, + transport: http(), +}); + +async function waitForTransaction(txId, label) { + for (let i = 0; i < 30; i++) { + await new Promise((r) => setTimeout(r, 2000)); + const { data } = await circleClient.getTransaction({ id: txId }); + if (data?.transaction?.state === "COMPLETE") return data.transaction.txHash; + if (data?.transaction?.state === "FAILED") throw new Error(label + " failed"); + } + throw new Error(label + " timed out"); +} + +async function main() { + // Step 1: Create two wallets (owner + validator) + const walletSet = await circleClient.createWalletSet({ name: "ERC8004 Agent Wallets" }); + const walletsResponse = await circleClient.createWallets({ + blockchains: ["ARC-TESTNET"], + count: 2, + walletSetId: walletSet.data?.walletSet?.id, + accountType: "SCA", + }); + + const ownerWallet = walletsResponse.data?.wallets?.[0]; + const validatorWallet = walletsResponse.data?.wallets?.[1]; + console.log("Owner: ", ownerWallet.address); + console.log("Validator:", validatorWallet.address); + + // Step 2: Register agent identity + const registerTx = await circleClient.createContractExecutionTransaction({ + walletAddress: ownerWallet.address, + blockchain: "ARC-TESTNET", + contractAddress: IDENTITY_REGISTRY, + abiFunctionSignature: "register(string)", + abiParameters: [METADATA_URI], + fee: { type: "level", config: { feeLevel: "MEDIUM" } }, + }); + const registerHash = await waitForTransaction(registerTx.data?.id, "registration"); + console.log("Registered:", "https://testnet.arcscan.app/tx/" + registerHash); + + // Step 3: Get agent ID from Transfer event + const latestBlock = await publicClient.getBlockNumber(); + const fromBlock = latestBlock > 10000n ? latestBlock - 10000n : 0n; + const transferLogs = await publicClient.getLogs({ + address: IDENTITY_REGISTRY, + event: parseAbiItem("event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)"), + args: { to: ownerWallet.address }, + fromBlock, + toBlock: latestBlock, + }); + const agentId = transferLogs[transferLogs.length - 1].args.tokenId.toString(); + console.log("Agent ID:", agentId); + + // Step 4: Record reputation (validator wallet) + const tag = "x402_payment_successful"; + const feedbackHash = keccak256(toHex(tag)); + const reputationTx = await circleClient.createContractExecutionTransaction({ + walletAddress: validatorWallet.address, + blockchain: "ARC-TESTNET", + contractAddress: REPUTATION_REGISTRY, + abiFunctionSignature: "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", + abiParameters: [agentId, "95", "0", tag, "", "", "", feedbackHash], + fee: { type: "level", config: { feeLevel: "MEDIUM" } }, + }); + await waitForTransaction(reputationTx.data?.id, "reputation"); + + // Step 5: Request + respond to validation + const requestHash = keccak256(toHex("validation_request_" + agentId)); + const validationReqTx = await circleClient.createContractExecutionTransaction({ + walletAddress: ownerWallet.address, + blockchain: "ARC-TESTNET", + contractAddress: VALIDATION_REGISTRY, + abiFunctionSignature: "validationRequest(address,uint256,string,bytes32)", + abiParameters: [validatorWallet.address, agentId, "ipfs://bafkreiexample", requestHash], + fee: { type: "level", config: { feeLevel: "MEDIUM" } }, + }); + await waitForTransaction(validationReqTx.data?.id, "validation request"); + + const validationResTx = await circleClient.createContractExecutionTransaction({ + walletAddress: validatorWallet.address, + blockchain: "ARC-TESTNET", + contractAddress: VALIDATION_REGISTRY, + abiFunctionSignature: "validationResponse(bytes32,uint8,string,bytes32,string)", + abiParameters: [requestHash, "100", "", "0x" + "0".repeat(64), "agent_verified"], + fee: { type: "level", config: { feeLevel: "MEDIUM" } }, + }); + await waitForTransaction(validationResTx.data?.id, "validation response"); + + console.log("Agent registration complete!"); + console.log("Explorer:", "https://testnet.arcscan.app/address/" + ownerWallet.address); +} + +main().catch(console.error); +``` + +## Expected Output +## How It Works + +1. **Two wallets** — owner registers the agent, validator records reputation (per ERC-8004, owners cannot self-attest) +2. **Identity registration** — mints an ERC-721 NFT on IdentityRegistry, giving the agent a unique onchain ID +3. **Reputation** — validator records feedback with a score and tag on ReputationRegistry +4. **Validation** — two-step request/response flow on ValidationRegistry proves the agent meets criteria + +## Integration with X402 + +This ERC-8004 identity can be combined with x402 payments for a complete agentic flow: +See the full working example: [github.com/consumeobeydie/arc-agent-api](https://github.com/consumeobeydie/arc-agent-api) + +## Resources + +- [Arc ERC-8004 Docs](https://docs.arc.network/arc/tutorials/register-your-first-ai-agent) +- [Arc Testnet Explorer](https://testnet.arcscan.app) +- [Circle Developer Console](https://console.circle.com) +- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004) diff --git a/docs/examples/erc8183-job-lifecycle.md b/docs/examples/erc8183-job-lifecycle.md new file mode 100644 index 0000000..d3087bf --- /dev/null +++ b/docs/examples/erc8183-job-lifecycle.md @@ -0,0 +1,5 @@ +# ERC-8183 Job Lifecycle on Arc Testnet + +Job ID: 110860 - Status: Completed - Budget: 5 USDC + +Full example: https://github.com/consumeobeydie/arc-agent-api diff --git a/docs/examples/unified-agentic-flow-example.md b/docs/examples/unified-agentic-flow-example.md new file mode 100644 index 0000000..af30473 --- /dev/null +++ b/docs/examples/unified-agentic-flow-example.md @@ -0,0 +1,65 @@ +# Unified Agentic Flow on Arc Testnet + +This example combines X402 payments, ERC-8004 identity, and ERC-8183 jobs into a single automated agent flow on Arc Testnet. + +## Overview + +A single agent wallet runs three protocols in sequence: + +- PHASE 1: X402 micropayment to access Arc Testnet data +- PHASE 2: ERC-8004 onchain identity registration +- PHASE 3: ERC-8183 job creation, funding, and completion + +## Architecture + +Main Agent (0x54b4B44749a95070560509B6Ec0be501665CcF63) +- Pays for API access with USDC (X402) +- Registers onchain identity (ERC-8004) +- Creates and completes a job (ERC-8183) + +## Contracts Used + +| Contract | Address | +|----------|---------| +| IdentityRegistry (ERC-8004) | 0x8004A818BFB912233c491871b3d84c89A494BD9e | +| ReputationRegistry (ERC-8004) | 0x8004B663056A597Dffe9eCcC1965A193B7388713 | +| ValidationRegistry (ERC-8004) | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272 | +| AgenticCommerce (ERC-8183) | 0x0747EEf0706327138c69792bF28Cd525089e4583 | + +## Live Results on Arc Testnet + +Main Agent: 0x54b4B44749a95070560509B6Ec0be501665CcF63 +Agent ID: 69828 +Job ID: 110935 +Job Status: Completed +Budget: 1 USDC + +## Flow Summary + +PHASE 1 - X402 Payment: +- Agent sends request to payment-gated API +- Receives HTTP 402 Payment Required +- Signs USDC payment automatically +- Receives Arc Testnet data + +PHASE 2 - ERC-8004 Identity: +- Registers identity on IdentityRegistry +- Records reputation score (95) +- Completes validation flow + +PHASE 3 - ERC-8183 Job: +- Creates job on AgenticCommerce contract +- Funds 1 USDC into escrow +- Provider submits deliverable hash +- Evaluator completes job, USDC released + +## Full Example Repository + +https://github.com/consumeobeydie/arc-agent-api + +## Resources + +- X402 Protocol: https://x402.org +- Arc ERC-8004 Docs: https://docs.arc.network/arc/tutorials/register-your-first-ai-agent +- Arc ERC-8183 Docs: https://docs.arc.network/arc/tutorials/create-your-first-erc-8183-job +- Arc Testnet Explorer: https://testnet.arcscan.app diff --git a/docs/examples/x402-agent-quickstart.md b/docs/examples/x402-agent-quickstart.md new file mode 100644 index 0000000..f0aa761 --- /dev/null +++ b/docs/examples/x402-agent-quickstart.md @@ -0,0 +1,152 @@ +# X402 Payment-Gated API on Arc Testnet + +This example shows how to build a payment-gated API on Arc Testnet using the [x402 protocol](https://x402.org) and Circle USDC. AI agents can autonomously pay for API access without human intervention. + +## Overview +## Prerequisites + +- Node.js v22+ +- A testnet wallet with USDC on Base Sepolia +- Arc Testnet RPC: `https://rpc.testnet.arc.network` + +Get testnet USDC from [faucet.circle.com](https://faucet.circle.com). + +## Installation + +```bash +mkdir arc-x402-api && cd arc-x402-api +npm init -y +npm install express x402-express x402-fetch viem dotenv +``` + +## Environment Setup + +```bash +# .env +ARC_RPC_URL=https://rpc.testnet.arc.network +ARC_CHAIN_ID=5042002 +SELLER_PRIVATE_KEY=your_testnet_private_key +PORT=3000 +``` + +## Server (Seller) + +```javascript +const express = require("express"); +const { paymentMiddleware } = require("x402-express"); +const dotenv = require("dotenv"); + +dotenv.config(); + +const app = express(); +const SELLER_ADDRESS = "0xYOUR_SELLER_ADDRESS"; + +// Protect endpoints with X402 +app.use(paymentMiddleware( + SELLER_ADDRESS, + { + "/api/arc-data": { + price: "$0.001", + network: "base-sepolia", + config: { description: "Arc Testnet network data" }, + }, + }, + { facilitatorUrl: "https://facilitator.circle.com" } +)); + +// Free endpoint +app.get("/health", (req, res) => { + res.json({ status: "ok", network: "Arc Testnet", chainId: 5042002 }); +}); + +// Paid endpoint +app.get("/api/arc-data", (req, res) => { + res.json({ + network: "Arc Testnet", + chainId: 5042002, + gasToken: "USDC", + finality: "sub-second deterministic", + contracts: { + USDC: "0x3600000000000000000000000000000000000000", + EURC: "0x3600000000000000000000000000000000000001", + }, + }); +}); + +app.listen(3000, () => console.log("Server running on port 3000")); +``` + +## Agent (Buyer) + +```javascript +const { createWalletClient, http } = require("viem"); +const { baseSepolia } = require("viem/chains"); +const { privateKeyToAccount } = require("viem/accounts"); +const { wrapFetchWithPayment } = require("x402-fetch"); +const dotenv = require("dotenv"); + +dotenv.config(); + +async function runAgent() { + const account = privateKeyToAccount(`0x${process.env.SELLER_PRIVATE_KEY}`); + + const walletClient = createWalletClient({ + account, + chain: baseSepolia, + transport: http(), + }); + + const { default: nodeFetch } = await import("node-fetch"); + const fetchWithPayment = wrapFetchWithPayment(nodeFetch, walletClient); + + // Agent automatically pays and fetches data + const response = await fetchWithPayment("http://localhost:3000/api/arc-data"); + const data = await response.json(); + console.log("Data received:", data); +} + +runAgent().catch(console.error); +``` + +## Running the Example + +Start the server: +```bash +node server.js +``` + +Run the agent: +```bash +node agent.js +``` + +Expected output: +## How X402 Works on Arc + +1. Agent sends a request to the paid endpoint +2. Server responds with **HTTP 402 Payment Required** +3. Agent reads the payment requirements (price, asset, payTo address) +4. Agent signs a USDC transfer authorization using **EIP-3009** +5. Agent resends the request with the `X-PAYMENT` header +6. Circle's facilitator verifies and settles the payment +7. Server returns the requested data + +## Arc Testnet Contract Addresses + +| Contract | Address | +|----------|---------| +| USDC | `0x3600000000000000000000000000000000000000` | +| EURC | `0x3600000000000000000000000000000000000001` | +| Gateway Wallet | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9` | + +## Full Example Repository + +[github.com/consumeobeydie/arc-agent-api](https://github.com/consumeobeydie/arc-agent-api) + +## Resources + +- [Arc Documentation](https://docs.arc.io) +- [X402 Protocol](https://x402.org) +- [Circle Developer Console](https://console.circle.com) +- [Arc Testnet Explorer](https://testnet.arcscan.app) +- [Circle Faucet](https://faucet.circle.com)