From df797c2286303fd8bda1e00f2669710d367ae3cb Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Sun, 7 Jun 2026 11:50:45 +0300 Subject: [PATCH 1/6] docs: add Foundry smart contract deployment guide for Arc Testnet --- .../deploying-smart-contracts-with-foundry.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/deploying-smart-contracts-with-foundry.md 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) From 8bb6acd9a66d1cb5fb4ee3091a6ca1748bbb5347 Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Sun, 7 Jun 2026 23:04:34 +0300 Subject: [PATCH 2/6] docs: add X402 payment-gated API example for Arc Testnet --- docs/examples/x402-agent-quickstart.md | 152 +++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/examples/x402-agent-quickstart.md 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) From 26824b23000cb6e563dbf69245e8f4f8818fc8e7 Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Mon, 8 Jun 2026 18:43:05 +0300 Subject: [PATCH 3/6] docs: add ERC-8004 AI agent registration example for Arc Testnet --- docs/examples/erc8004-agent-registration.md | 180 ++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 docs/examples/erc8004-agent-registration.md 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) From ce0078db2eeea7959bbb7c76808348e51f23d5b0 Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Mon, 8 Jun 2026 19:10:09 +0300 Subject: [PATCH 4/6] docs: add ERC-8183 job lifecycle example for Arc Testnet --- docs/examples/erc8183-job-lifecycle.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/examples/erc8183-job-lifecycle.md 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 From e73a1cebf1a579f1042058e24ad5966877b5d399 Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Mon, 8 Jun 2026 20:03:33 +0300 Subject: [PATCH 5/6] docs: add unified agentic flow example combining X402, ERC-8004 and ERC-8183 --- docs/examples/unified-agentic-flow-example.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/examples/unified-agentic-flow-example.md 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 From f7e9c6e82ecae4e170f71d234a8f662d311f3d4a Mon Sep 17 00:00:00 2001 From: consumeobeydie Date: Mon, 8 Jun 2026 20:54:50 +0300 Subject: [PATCH 6/6] docs: add Arc Intelligence Dashboard example for Arc Testnet --- docs/examples/arc-intelligence-dashboard.md | 56 +++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/examples/arc-intelligence-dashboard.md 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