Contract Architecture

Weavrn is built on 7 smart contracts deployed on Base. Each contract handles a specific piece of the protocol.

System Diagram

                    ┌──────────────┐
                    │ WeavrnToken  │
                    │   (ERC-20)   │
                    └──────┬───────┘
                           │ funds
              ┌────────────┼────────────┐
              ▼            ▼            ▼
     ┌────────────┐ ┌────────────┐ ┌────────────────┐
     │   Social   │ │   Usage    │ │    Weavrn      │
     │   Mining   │ │ Incentives │ │   Treasury     │
     └────────────┘ └─────┬──────┘ └───────┬────────┘
                          │                │ fees
                    ┌─────┴──────┐   ┌─────┴──────┐
                    │  Payment   │   │   Escrow   │
                    │   Router   │   │   Router   │
                    └─────┬──────┘   └─────┬──────┘
                          │                │
                          └───────┬────────┘
                                  │ checks
                          ┌───────┴────────┐
                          │ AgentRegistry  │
                          └────────────────┘

Contracts

WeavrnToken

ERC-20 token with 1 billion supply. Standard OpenZeppelin implementation — all tokens minted to the deployer at construction.

AgentRegistry

On-chain identity for AI agents. One registration per address. Tracks agent ID, name, metadata URI, and active status. The owner can deactivate/reactivate agents.

• Used by PaymentRouter and EscrowRouter to verify both parties are active agents
• Agent IDs start at 1 (0 = unregistered)

PaymentRouter

Handles agent-to-agent payments in ETH and any ERC-20 token. Deducts a configurable fee (default 0.1%, max 5%) and sends it to the treasury. Tracks per-agent volume, payment count, and unique recipients.

EscrowRouter

Conditional payments with deadlines. Sender locks funds, then either releases (fee deducted) or refunds after deadline (no fee). Independent from PaymentRouter — separate fee rate (default 0.5%), separate volume tracking.

UsageIncentives

Distributes WVRN rewards to agents. Two mechanisms:

• First-use bonus: 100 WVRN for making your first payment (self-service claim)
• Volume rebates: Protocol owner settles rebates based on agent volume, agents claim

SocialMining

Block-based WVRN distribution for social engagement. The protocol owner settles rewards per-user per-block based on X engagement scores. Users claim on-chain.

WeavrnTreasury

Collects protocol fees (ETH + ERC-20) and distributes WVRN to pools (mining, incentives). Epoch-capped to prevent over-distribution — each pool has a maximum WVRN allocation per epoch (30 days).

Key Design Principles

• Non-custodial: Agents hold their own keys. No deposits or lockups (except escrow).
• Permissionless: Anyone can register and start transacting. No approval process.
• Fee-on-transfer: Fees are deducted at transaction time, not settled separately.
• Honor commitments: Deactivating an agent doesn’t affect existing escrows — they can still be released or refunded.
• Owner-settled, user-claimed: The protocol owner settles rewards/rebates on-chain. Users only pay gas for claims.