Smart Accounts¶

Lango includes an ERC-7579 modular smart account layer that gives agents controlled autonomy over on-chain operations. The system uses Safe-based smart accounts with session key-scoped permissions, an off-chain policy engine, and ERC-4337 paymaster integration for gasless USDC transactions.

Package: internal/smartaccount/

Overview¶

The smart account subsystem coordinates five components to enable secure, policy-bounded on-chain execution:

• Account Manager -- Safe deployment via CREATE2 and UserOp construction with ERC-4337 v0.7 signing
• Session Manager -- hierarchical session key lifecycle (create, list, revoke) with parent/child relationships
• Policy Engine -- off-chain pre-flight validation with spending limits, target/function allowlists, and risk integration
• Module Registry -- ERC-7579 module descriptor management (validator, executor, fallback, hook)
• Bundler Client -- JSON-RPC communication with an external ERC-4337 bundler

graph TB
    Agent[Agent Tool Call] --> SM[Session Manager]
    Agent --> PE[Policy Engine]
    SM --> |sign UserOp| AM[Account Manager]
    PE --> |validate call| AM
    AM --> |submit UserOp| BC[Bundler Client]
    AM --> |install/uninstall| MR[Module Registry]
    BC --> |eth_sendUserOperation| Bundler[ERC-4337 Bundler]
    Bundler --> EP[EntryPoint Contract]
    EP --> SA[Safe Smart Account]
    SA --> |delegate call| Modules[ERC-7579 Modules]

    PM[Paymaster Provider] --> |paymasterAndData| AM

    style Agent fill:#7c3aed,color:#fff
    style SM fill:#7c3aed,color:#fff
    style PE fill:#7c3aed,color:#fff
    style AM fill:#7c3aed,color:#fff
    style BC fill:#7c3aed,color:#fff
    style MR fill:#7c3aed,color:#fff
    style PM fill:#2563eb,color:#fff
    style Bundler fill:#22c55e,color:#fff
    style EP fill:#22c55e,color:#fff
    style SA fill:#22c55e,color:#fff
    style Modules fill:#22c55e,color:#fff

UserOp Submission Flow¶

When the agent executes a contract call, the system follows a two-phase paymaster flow:

1. Build UserOperation with nonce from EntryPoint
2. Phase 1: Obtain stub paymasterAndData for gas estimation
3. Estimate gas via bundler (eth_estimateUserOperationGas)
4. Phase 2: Obtain final signed paymasterAndData with optional gas overrides
5. Compute UserOp hash (ERC-4337 v0.7 PackedUserOperation format)
6. Sign with wallet and submit via bundler (eth_sendUserOperation)

Session Keys¶

Session keys provide scoped, time-limited signing authority over the smart account. Each key is an ECDSA key pair generated on-demand, with private key material optionally encrypted via CryptoProvider.

Hierarchy¶

Session keys support a parent/child hierarchy:

• Master sessions (parentId = empty) -- root-level keys with full policy bounds
• Task sessions (parentId = master session ID) -- child keys whose policy is the intersection of parent and child constraints

When a child session is created, its policy is automatically tightened to the intersection of the parent's policy: later validAfter, earlier validUntil, smaller spendLimit, and the intersection of allowedTargets and allowedFunctions.

Lifecycle¶

stateDiagram-v2
    [*] --> Created: session_key_create
    Created --> Active: validAfter reached
    Active --> Expired: validUntil passed
    Active --> Revoked: session_key_revoke
    Revoked --> [*]
    Expired --> Cleaned: CleanupExpired
    Cleaned --> [*]

Session Policy¶

Each session key carries a SessionPolicy that defines its operational bounds:

Configuration¶

Revocation¶

Revoking a session key cascades to all children:

1. Mark the key as revoked = true
2. Recursively revoke all child sessions via ListByParent
3. If an on-chain revocation callback is set, revoke on the validator contract

Paymaster¶

The paymaster subsystem enables gasless USDC transactions via ERC-4337 v0.7 paymasters. Providers are available in two modes: RPC (API-based) and permit (on-chain EIP-2612, no API key required).

Providers¶

Recovery and Fallback¶

Each provider can be wrapped with RecoverableProvider for retry logic:

• Transient errors (e.g. timeout): retry with exponential backoff up to maxRetries
• Permanent errors (e.g. rejected, insufficient tokens): fail immediately
• Fallback modes when retries are exhausted:
  • abort -- transaction fails (default)
  • direct -- fall back to direct gas payment (user pays gas)

USDC Approval¶

Before gasless transactions can work, the smart account must approve the paymaster to spend USDC tokens. The paymaster_approve tool builds an ERC-20 approve(address,uint256) call and executes it via UserOp.

Configuration¶

Policy Engine¶

The policy engine performs off-chain pre-flight validation before any contract call reaches the bundler. It checks each call against a HarnessPolicy bound to the smart account address and tracks cumulative spending via SpendTracker.

Harness Policy¶

Validation Order¶

The validator checks constraints in this order:

1. MaxTxAmount -- reject if call.Value > policy.MaxTxAmount
2. AllowedTargets -- reject if target address is not in the whitelist
3. AllowedFunctions -- reject if function selector is not in the whitelist
4. DailyLimit -- reject if dailySpent + call.Value > dailyLimit
5. MonthlyLimit -- reject if monthlySpent + call.Value > monthlyLimit

The spend tracker automatically resets daily (24h window) and monthly (30-day window) counters.

Policy Merging¶

When master and task policies coexist, MergePolicies produces the intersection (tighter bound for each field): the smaller of each limit, the higher of each risk score, and the address/function intersection of each list.

On-Chain Sync¶

The Syncer bridges Go-side harness policies with the on-chain LangoSpendingHook contract:

• PushToChain -- writes MaxTxAmount, DailyLimit, MonthlyLimit as setLimits(perTxLimit, dailyLimit, cumulativeLimit)
• PullFromChain -- reads on-chain config and updates the Go-side policy
• DetectDrift -- compares Go-side and on-chain policies, returning a DriftReport with any differences

Risk Integration¶

The policy engine accepts a RiskPolicyFunc callback that dynamically generates policy constraints from the economy risk assessor based on peer DID. This enables risk-based spending limits.

Module Registry¶

The module registry manages ERC-7579 module descriptors. Each module has a ModuleDescriptor with name, address, type, version, and optional init data.

Module Types¶

Module Installation¶

Module installation goes through the Safe7579 adapter:

1. Encode installModule(moduleType, address, initData) via Safe7579 ABI
2. Build and sign a UserOp with the encoded calldata
3. Submit via bundler
4. Track the module locally in the Manager.modules slice

Uninstallation follows the same pattern with uninstallModule.

Configuration¶

Agent Tools¶

Integration Points¶

The smart account system integrates with several other Lango subsystems:

• Economy Risk Engine -- the policy engine accepts a RiskPolicyFunc callback to dynamically adjust spending limits based on peer trust scores (see P2P Economy)
• Security Sentinel -- sentinel anomaly detection can trigger emergency session revocation via the session manager's RevokeAll method
• On-Chain Spending Tracker -- the session_execute tool records spending to an on-chain tracker, which feeds back into the policy engine's budget tracking
• Escrow Executor -- the LangoEscrowExecutor module enables the smart account to interact with escrow contracts directly (see Contracts)

Configuration¶

Settings: lango settings -> Smart Account

{
  "smartAccount": {
    "enabled": true,
    "factoryAddress": "0x...",
    "entryPointAddress": "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
    "safe7579Address": "0x...",
    "fallbackHandler": "0x...",
    "bundlerURL": "https://bundler.example.com/rpc",
    "session": {
      "maxDuration": "24h",
      "defaultGasLimit": "500000",
      "maxActiveKeys": 10
    },
    "paymaster": {
      "enabled": true,
      "provider": "circle",
      "mode": "permit",
      "tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "paymasterAddress": "0x31BE08D380A21fc740883c0BC434FcFc88740b58",
      "fallbackMode": "abort"
    },
    "modules": {
      "sessionValidatorAddress": "0x...",
      "spendingHookAddress": "0x...",
      "escrowExecutorAddress": "0x..."
    }
  }
}