Roda
AboutHow to UseDocsFaucet
Back to Dashboard

Technical Documentation

Understand the smart contract state machine, decentralized consensus rules, and execution flow of Roda on Arc Network.

Quick Start Guide

Follow this flow to test a complete savings circle end-to-end:

  1. Connect Wallet: Click "Connect Wallet" on the home page and switch your network to Arc Testnet (Chain ID: 5042002).
  2. Faucet: Fund your connected wallet with native USDC (for gas) and ERC-20 USDC (for contributions) via faucet.circle.com.
  3. Create: Click the "Create Circle" tab, specify a contribution amount (e.g. 10 USDC), the number of members (e.g. 3), and round duration (e.g. 60 seconds for a quick test).
  4. Join: Distribute the circle address to 2 other wallets (or test using separate browser profiles). Each wallet must click Approve & Join to lock their collateral.
  5. Rotate: In each round:
    • All members call contribute() to pay their share.
    • Once paid, or if the deadline passes, anyone can call closeRound() to advance.
    • The designated round beneficiary claims the collected pot using claimPayout().
    • If a member is at risk of defaulting, the AI Liquidity Guardian can trigger a bailout.
  6. Settle: Once the last round closes, all members call withdrawCollateral() to reclaim their security deposits.

State Machine, Security & Grace Period

Each SavingsCircle operates as a rigid, production-grade state machine with OpenZeppelin AccessControl and emergency circuit breakers:

Recruiting --[memberCount joins, locks collateral]--> Active Active: per round --[contribute -> closeRound -> claim]--> Completed Completed --[everyone withdraws collateral]--> Terminated Emergency: [PAUSER_ROLE -> pause() -> emergencyWithdraw()]

1. OpenZeppelin AccessControl & Pausable Circuit Breakers

Smart contracts implement role-based access control (PAUSER_ROLE, GUARDIAN_ROLE, DEFAULT_ADMIN_ROLE). In emergency situations or flagged security anomalies, authorized Multi-sig or Timelock addresses can trigger pause() to freeze round state transactions. While paused, emergency collateral recoveries can be executed via emergencyWithdraw().

2. Configurable Default Grace Period (24h Default)

To prevent premature collateral forfeiture caused by transient network delays or wallet RPC issues, Roda enforces a configurable Default Grace Period (default: 24 hours / 86,400 seconds; minimum: 1 hour, maximum: 7 days). If a round deadline passes, callers attempting to force-close the round before the grace period expires receive an explicit on-chain GracePeriodActive() revert.

3. Circle CCTP 1-Click Bridge & Join

Roda integrates Circle's Cross-Chain Transfer Protocol (CCTP) to enable seamless 1-click deposits. Users on Base, Arbitrum One, Ethereum Mainnet, or OP Mainnet can bridge USDC directly into Arc Testnet circle escrows without multi-step manual bridging.

4. Decimal Conversion Precision

Arc L1 utilizes native gas USDC (18 decimals) alongside ERC-20 USDC (6 decimals). All contract calculations utilize explicit to6Decimals() and to18Decimals() pure conversion helpers to guarantee zero rounding loss across token contexts.

AI Liquidity Guardian & ERC-8004

Roda integrates autonomous agent automation with verified on-chain identities to secure collaborative saving pools.

1. Autonomous Credit Protection

The AI Liquidity Guardian acts as an on-chain automated risk engine. When a member is in danger of defaulting, the Guardian can autonomously decide to perform a liquidity bailout:

  • The Guardian assesses the member's collateral, debt, and payment history using an Autonomous AI Risk Engine.
  • If approved, the Guardian's Circle Developer-Controlled Wallet automatically signs and broadcasts transactions to execute the bailout on Arc Testnet, keeping the savings circle liquid.

2. ERC-8004 Agent Identity & Reputation

To ensure trustless execution, the AI Guardian is registered as an on-chain identity using the ERC-8004 standard:

  • The agent is minted as an identity NFT on Arc's IdentityRegistry (Agent ID: #849938).
  • Following each credit assessment, a validator wallet submits a giveFeedback rating to the on-chain ReputationRegistry.
  • The overall reputation score and historical assessments are calculated directly from on-chain logs.

3. Monetized x402 Nanopayments API

External agents and dApps can purchase real-time AI risk assessment reports via the x402 HTTP 402 Payment Required protocol at /api/risk-report:

  • Price per query: $0.001 USDC (nanopayment scale).
  • Monetization Flow: Micro-payment signatures settle gas-free to the Guardian's Circle Developer Wallet.
  • Live Chain Reads: Pulls real collateral, debt, and payment history from Arc Testnet smart contracts before generating AI risk analysis.

How to Test the Guardian & Terminal:

  1. Enter any active circle dashboard and locate the AI Liquidity Guardian panel.
  2. Verify the agent's on-chain status under the Onchain Identity Verified widget.
  3. Select a member from the dropdown list and click Analyze Risk to fetch a real-time risk profile and AI rationale.
  4. Click ▶ Run AI Security Audit inside the AI Guardian Terminal to stream real-time timestamped logs of on-chain verification, AI risk reasoning, and ERC-8004 reputation logs.
  5. Call GET /api/risk-report?circle=0x...&member=0x... to test the x402 Nanopayment API challenge response.

Arc Decimal Contexts

Arc features a stablecoin-first native architecture. However, this introduces two decimal contexts that must never be mixed:

  • Native Gas USDC: 18 decimals. Used for gas fees and checked using standard wallet balances (e.g. useBalance).
  • ERC-20 USDC: 6 decimals. Used for all contract token transfers, deposits, pots, and payouts (contract address: 0x3600000000000000000000000000000000000000).
Warning: Sending 18-decimal values to the ERC-20 contract will revert or cause massive overflow issues. Always use the built-in parsing helpers: parseUsdc(x) targets 6 decimals; parseGas(x) targets 18.

Smart Contracts Reference

The contract codebase consists of two core smart contracts compiled with Solidity 0.8.28:

1. CircleFactory.sol

Deploys and indexes individual savings circles for public discovery.

function createCircle(uint256 contributionAmount, uint8 memberCount, uint256 roundDuration) external returns (address); function getCircles(uint256 offset, uint256 limit) external view returns (CircleInfo[] memory);

2. SavingsCircle.sol

Manages individual circles, escrow deposits, round tracking, and default claims.

function join() external; function contribute() external; function closeRound() external; function claimPayout(uint256 round) external; function withdrawCollateral() external;

Mathematical Solvency & Formal Verification

Roda is architected with a provable zero-bad-debt guarantee. Every financial operation is bound by strict invariant constraints verified by 17 Foundry automated unit & invariant test suites.

1. 100% Escrow Solvency Invariant

For a circle with N members and contribution C, every member locks 1 x C as collateral during recruitment. For any number of defaulting members D ≤ N - 1, the contract's total USDC balance satisfies:

Balance(Contract) >= Sum(ClaimablePayouts) + Sum(ActiveCollateral)

This invariant guarantees that even under consecutive member default permutations, the escrow balance is 100% solvent.

2. Automated Security & Timing Attack Tests

  • Recruiting Timeout Refund: If a circle fails to reach full capacity before the recruiting deadline, members can withdraw 100% of their locked collateral with zero loss.
  • Front-Running & Timing Attack Prevention: Round settlement (closeRound()) before deadline reverts with RoundNotOver(), and unauthorized payout claims revert with NotBeneficiary().
  • Circle API Resiliency: Server endpoints implement exponential backoff retry logic (retryAsync) to handle Circle API rate limits and network latency.

3. Open Source License & Audit Roadmap

Roda is open-source software released under the MIT License. Independent third-party security audits (Trail of Bits / OpenZeppelin standards) will be published prior to Arc Mainnet deployment.