Architecture Overview

ClawWallet is a modular protocol of 12+ smart contracts organized into four pillars: Agent Wallets, Identity, Skills, and Economics. Every contract is deployed on Abstract Chain (zkSync ERA, Chain ID 2741).

System Diagram

graph TB
    subgraph User Layer
        OWNER[Human Owner / EOA]
        AGENT[AI Agent]
    end

    subgraph Core Wallet Infrastructure
        FACTORY[ClawWalletFactory V2<br/>0xf6B9...1cc]
        WALLET[ClawWallet<br/>Smart Contract Wallet]
        PAYMASTER[ClawPaymaster<br/>0x7BBB...dAf]
    end

    subgraph ERC-8004 Identity
        IDENTITY[IdentityRegistry V2<br/>0x0194...E5<br/>.claw ERC-721]
        REPUTATION[ReputationRegistry<br/>0x2AAa...9F]
        VALIDATION[ValidationRegistry<br/>0x0703...dc]
    end

    subgraph Skills
        REGISTRY[SkillRegistry V2<br/>0xb991...1b]
        SKILL1[Skill Contract A]
        SKILL2[Skill Contract B]
    end

    subgraph Token Economics
        PINCH[PinchToken<br/>0xF8e8...12]
        STAKING[PinchStaking<br/>0x4D43...d7]
        DIVIDENDS[ClawDividends<br/>0x3441...06]
        LAUNCHER[TokenLauncher<br/>0x89B9...b5]
        PRESALE[PinchPresale<br/>0x2f40...7B]
    end

    OWNER -->|deploys via| FACTORY
    FACTORY -->|creates| WALLET
    AGENT -->|operates| WALLET
    WALLET -->|gasless txs via| PAYMASTER
    WALLET -->|registers identity| IDENTITY
    WALLET -->|gets rated| REPUTATION
    WALLET -->|gets validated| VALIDATION
    WALLET -->|calls| SKILL1
    WALLET -->|calls| SKILL2
    REGISTRY -->|approves| SKILL1
    REGISTRY -->|approves| SKILL2
    PINCH -->|staked in| STAKING
    IDENTITY -->|holders earn via| DIVIDENDS
    WALLET -->|launches tokens via| LAUNCHER

Contract Relationships

Wallet Creation Flow

1. Owner calls ClawWalletFactory.createWallet(agentAddress) with 0.0005 ETH fee
2. Factory uses zkSync ERA's ContractDeployer.create2Account() for deterministic deployment
3. A new ClawWallet instance is deployed and flagged as AA-compatible (Version1)
4. Factory calls ClawWallet.initialize(owner, agent, skillRegistry) — only the factory can do this (immutable _factory check prevents front-running)
5. Factory stores the mapping: agentToWallet[agent] = wallet

Owner → ClawWalletFactory.createWallet(agent)
           │
           ├── DEPLOYER_SYSTEM_CONTRACT.create2Account(salt, bytecodeHash, ...)
           │     └── ClawWallet deployed at deterministic address
           │
           ├── ClawWallet.initialize(owner, agent, skillRegistry)
           │
           └── agentToWallet[agent] = walletAddress

Identity Registration Flow

1. Owner calls ClawWallet.erc8004Register(agentURI) on the wallet
2. Wallet calls ERC8004IdentityRegistry.register(agentURI) with 0.001 ETH mint fee
3. Registry mints an ERC-721 NFT (the .claw domain) to the wallet
4. Registry automatically sets agentWallet metadata to the wallet address
5. The agentId (token ID) is stored in the wallet's erc8004AgentId

Gasless Transaction Flow

1. Agent submits a transaction to the Abstract Chain mempool
2. ClawPaymaster.validateSponsorship(wallet, gasAmount) checks eligibility:
   • Is the wallet within its daily gas limit?
   • Does the paymaster have sufficient balance?
3. If valid, paymaster sponsors the gas — agent pays nothing
4. After execution, recordSponsorship() updates the wallet's daily gas usage

Agent → Transaction → ClawPaymaster validates
                        │
                        ├── Check SponsorshipMode (FREE_TIER / REVENUE_FUNDED / TOKEN_PAID)
                        ├── Check daily gas limit
                        ├── Check paymaster balance
                        │
                        └── Sponsor gas → Transaction executes → Record usage

Skill Execution Flow

1. Owner or Agent calls ClawWallet.installSkill(skillAddress) to whitelist a skill
2. When executing, wallet checks _installedSkills[target] — agents can only call installed skills
3. If the target is an installed skill and a skillRegistry is set, the wallet calls recordSkillCall() on the registry for usage tracking
4. The skill contract executes and returns results through the wallet

Fee Distribution Flow

1. Protocol fees accumulate from various sources:
   • Wallet creation fees (0.0005 ETH → treasury)
   • Identity mint fees (0.001 ETH → registry, withdrawable to treasury)
   • Skill registration fees (0.0005 ETH → registry, withdrawable to treasury)
   • Agent trading fees (from AgentToken transfers → agent wallet + protocol)
2. Agents deposit their fee share into ClawDividends.depositETH()
3. An operator creates epochs with off-chain snapshots of .claw NFT holders
4. Holders claim their pro-rata share: perNFTShare × nftCount

Access Control Model

┌─────────────────────────────────────────────────────────┐
│                    ClawWallet                            │
│                                                         │
│  Owner (EOA)                                            │
│  ├── Full control: spending limits, session keys, skills│
│  ├── ERC-8004 registry configuration                    │
│  ├── Emergency freeze / unfreeze                        │
│  └── Co-signer management                               │
│                                                         │
│  Agent (EOA or Contract)                                │
│  ├── Execute txs (within spending limits)               │
│  ├── Call installed skills only                         │
│  ├── Install / uninstall skills                         │
│  ├── Add / revoke session keys                          │
│  └── Update ERC-8004 agent URI                          │
│                                                         │
│  Session Keys (temporary)                               │
│  ├── Time-limited (validUntil timestamp)                │
│  ├── Spending-capped (independent limit)                │
│  └── Target-restricted (allowedTargets whitelist)       │
│                                                         │
│  Co-Signer (optional)                                   │
│  └── Emergency freeze only                              │
└─────────────────────────────────────────────────────────┘

Contract Dependencies

Contract	Depends On
ClawWallet	ClawWalletFactory (deployer), ClawSkillRegistry (call tracking), ERC-8004 registries
ClawWalletFactory	ClawWallet (bytecode hash), zkSync DEPLOYER_SYSTEM_CONTRACT
ClawPaymaster	ClawWalletFactory (wallet validation)
ERC8004IdentityRegistry	Standalone (ERC-721)
ERC8004ReputationRegistry	ERC8004IdentityRegistry (agent ownership verification)
ERC8004ValidationRegistry	ERC8004IdentityRegistry (agent ownership verification)
ClawSkillRegistry	Standalone
PinchToken	Standalone (ERC-20)
PinchStaking	PinchToken
PinchPresale	PinchToken
ClawDividends	ERC8004IdentityRegistry (for .claw holder snapshots)
ClawTokenLauncher	Deploys new AgentToken instances

Security Model

Immutable Factory Binding (C-01 Fix)

ClawWallet receives the factory address as an immutable constructor argument (_factory). Only this factory can call initialize(), preventing front-running attacks where a malicious actor could initialize a wallet before the factory.

Epoch Challenge Period (C-02 Fix)

ClawDividends implements a 6-hour challenge period on new epochs. During this window, the owner can cancel a suspicious epoch. Epochs are only claimable after finalizedAt timestamp passes.

Buffered Rewards (H-01 Fix)

PinchStaking buffers reward deposits made when totalWeight == 0. These rewards are distributed to the first staker(s) when they enter, preventing permanent reward loss.

Network Configuration

const abstractChain = {
  id: 2741,
  name: 'Abstract Mainnet',
  network: 'abstract',
  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://api.mainnet.abs.xyz'] },
  },
  blockExplorers: {
    default: { name: 'AbsScan', url: 'https://abscan.org' },
  },
};