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 & Lifecycle

Each SavingsCircle operates as a rigid, trustless state machine to protect funds from defaults:

Recruiting --[memberCount joins, locks collateral]--> Active Active: per round --[contribute -> closeRound -> claim]--> Completed Completed --[everyone withdraws collateral]--> Terminated

Collateral Protection: When joining a circle, members must escrow an amount exactly equal to one round's contribution. If a member fails to contribute by the round's deadline, closeRound() automatically recovers their missing payment by burning a portion of their locked collateral. This guarantees the beneficiary always receives the full payout.

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 DeepSeek AI.
  • 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.
  • 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.

How to Test the Guardian:

  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. If approved, click Execute Automated Injection to trigger the live Circle-powered transaction.

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;