diff --git a/docs/examples/smart-economy-engine.md b/docs/examples/smart-economy-engine.md new file mode 100644 index 0000000..b6a0925 --- /dev/null +++ b/docs/examples/smart-economy-engine.md @@ -0,0 +1,78 @@ +# Arc Smart Economy Engine Example + +This example shows how to build a self-sustaining autonomous agent economy on Arc Testnet that uses an X402-gated market oracle to make dynamic vault strategy decisions. + +## Overview + +The Smart Economy Engine combines three Arc Testnet primitives into one autonomous loop: + +1. MultiAgentOrchestrator — agents hire each other and complete missions +2. ArcUSDCVault (ERC-4626) — mission earnings automatically enter a yield-bearing vault +3. X402 micropayments — the engine pays 0.001 USDC per cycle to purchase a market signal from an oracle + +Each cycle, the engine buys a BULLISH/NEUTRAL/BEARISH signal and adjusts its behavior: +- BULLISH: larger mission budget (1.5x), distribute vault yield +- NEUTRAL: normal mission budget (1.0x) +- BEARISH: smaller mission budget (0.5x), conserve capital + +## Architecture + +X402 Oracle (local server) + | + | pays 0.001 USDC per request + v +Smart Economy Engine (Node.js) + |-- reads signal: BULLISH / NEUTRAL / BEARISH + |-- opens mission with dynamic budget + |-- Agent A assigns, hires Agent B + |-- Agent B completes mission + |-- routes payout to ERC-4626 vault + |-- if BULLISH + threshold: distributes yield + +## Key Contracts on Arc Testnet + +| Contract | Address | +|----------|---------| +| MultiAgentOrchestrator | 0xe81f5BA4181eA29061C3C229c8D6EB4cFE56639C | +| ArcUSDCVault (ERC-4626) | 0x6C13dA317B65474299F6fDee02daDd6626Eb2BFe | +| Memo precompile | 0x5294E9927c3306DcBaDb03fe70b92e01cCede505 | + +## Live Results (3 cycles) + +Cycle 1: BEARISH (score 1) -> 1.5 USDC mission, vault: 13.00 -> 13.25 USDC +Cycle 2: BEARISH (score 39) -> 1.5 USDC mission, vault: 13.25 -> 13.50 USDC +Cycle 3: BULLISH (score 89) -> 4.5 USDC mission + yield distributed, vault: 13.50 -> 17.75 USDC + +Final state: +- Vault Assets: 17.75 USDC (+36% from start) +- Agent B Shares: 10,750,000 avUSDC (+34%) +- Agent A Reputation: 145 +- Agent B Reputation: 124 +- Total Missions: 11 + +## X402 Oracle Flow + +The oracle server exposes a paywall endpoint. Each cycle the engine: +1. Sends GET /premium/market -> receives 402 Payment Required +2. Generates a payment proof (keccak256 of payment intent) +3. Resends with X-PAYMENT header -> receives market signal JSON +4. Uses signal.action and signal.mission_multiplier for dynamic decisions + +## Known Limitation: callWithMemo + gas estimation + +The Memo precompile (callWithMemo) reverts during eth_estimateGas / eth_call simulation but executes successfully as a direct signed transaction. This affects any SDK that estimates gas before sending (viem writeContract, Circle Developer Controlled Wallets). See issue #189 for details. + +Workaround: use cast send with raw calldata for Memo transactions. + +## GitHub Repositories + +- Smart Economy Engine: https://github.com/consumeobeydie/arc-agent-api/blob/main/src/smart-economy-engine.js +- X402 Oracle Server: https://github.com/consumeobeydie/hermes-arc-x402 +- ERC-4626 Vault: https://github.com/consumeobeydie/arc-vault +- Multi-Agent Orchestrator: https://github.com/consumeobeydie/arc-multi-agent + +## Resources + +- Arc Testnet Explorer: https://testnet.arcscan.app +- Arc Docs: https://docs.arc.io +- ERC-4626 Standard: https://eips.ethereum.org/EIPS/eip-4626 diff --git a/docs/examples/transaction-memo-integration.md b/docs/examples/transaction-memo-integration.md new file mode 100644 index 0000000..b7ed779 --- /dev/null +++ b/docs/examples/transaction-memo-integration.md @@ -0,0 +1,43 @@ +# Arc Transaction Memos: Multi-Agent Orchestrator Integration Example + +This example shows how to integrate Arc's Transaction Memos feature with an existing contract without modifying it, using the predeployed Memo contract on Arc Testnet. + +## Overview + +Transaction Memos (announced June 18, 2026) let you attach structured context to any contract call via a predeployed Memo contract, which routes the inner call through the CallFrom precompile so the original msg.sender is preserved. The Memo event is only emitted if the inner call succeeds, giving downstream systems a clean reconciliation signal. + +## Predeployed Contracts on Arc Testnet + +| Contract | Address | +|----------|---------| +| Memo | 0x5294E9927c3306DcBaDb03fe70b92e01cCede505 | +| Multicall3From | 0x522fAf9A91c41c443c66765030741e4AaCe147D0 | + +## Function Signature + +function callWithMemo(address target, bytes calldata data, bytes32 correlationId, string calldata memo) external returns (bool success, bytes memory result) + +Selector: 0xc3b2c4f8 + +This signature was derived by inspecting the Memo contract bytecode dispatcher and decoding a real on-chain transaction calldata to confirm parameter types, since the ABI was not yet published when this example was built. + +## Common Pitfalls + +- Empty revert data: behavior with cast call --from may differ from an actual sent transaction. +- Inner call must succeed: the Memo event only emits when the wrapped call succeeds. +- bytes32 correlationId must be exactly 32 bytes. + +## Live Verified Example + +Tested against the MultiAgentOrchestrator contract from arc-multi-agent: + +- Memo contract: 0x5294E9927c3306DcBaDb03fe70b92e01cCede505 +- Target: 0xe81f5BA4181eA29061C3C229c8D6EB4cFE56639C +- Tx: https://testnet.arcscan.app/tx/0x7532ce470169e2db2be43e5f9c43dd523d21e9071c04268ff5941f8ca839ef7b +- Status: Success, confirmed in 0.58 seconds + +## Resources + +- Arc Transaction Memos announcement: https://community.arc.io/home/blogs/arc-transaction-memos-structured-transaction-context-for-financial-workflows-on-arc-2026-06-18 +- Arc Contract Addresses: https://docs.arc.io/arc/references/contract-addresses +- Full implementation: https://github.com/consumeobeydie/arc-agent-api