P2P Economy¶

Lango includes a P2P economy layer that manages the financial lifecycle of inter-agent transactions. It consists of five sub-systems: Budget Manager, Risk Assessor, Dynamic Pricer, Negotiation Engine, and Escrow Service.

Overview¶

The economy layer coordinates spending, risk, pricing, negotiation, and settlement for paid P2P tool invocations:

• Budget Manager -- per-task spending limits with threshold alerts and hard caps
• Risk Assessment -- trust-based payment strategy routing (DirectPay, Escrow, EscrowWithZK, Reject)
• Dynamic Pricing -- peer-specific discounts based on trust score and volume
• Negotiation Engine -- multi-round price negotiation protocol with auto-negotiation
• Escrow Service -- milestone-based escrow with dispute resolution and on-chain settlement

graph LR
    BM[Budget Manager] --> RA[Risk Assessor]
    RA --> DP[Dynamic Pricer]
    DP --> NE[Negotiation Engine]
    NE --> ES[Escrow Service]
    ES --> ST[Settlement]

    style BM fill:#7c3aed,color:#fff
    style RA fill:#7c3aed,color:#fff
    style DP fill:#7c3aed,color:#fff
    style NE fill:#7c3aed,color:#fff
    style ES fill:#7c3aed,color:#fff
    style ST fill:#22c55e,color:#fff

Budget Manager¶

The budget manager enforces per-task spending limits. Each task gets an isolated budget that tracks spending against a configurable cap.

Configuration¶

Agent Tools¶

Events¶

Risk Assessment¶

The risk assessor evaluates each transaction and recommends a payment strategy based on peer trust score, transaction amount, and output verifiability.

Risk Levels¶

Configuration¶

Agent Tools¶

Dynamic Pricing¶

The dynamic pricer adjusts tool prices per-peer based on trust and transaction volume. High-trust peers receive a trust discount, and high-volume peers receive a volume discount. A configurable minimum price floor prevents prices from dropping too low.

Configuration¶

Agent Tools¶

Negotiation¶

The negotiation engine supports multi-round price negotiation between peers. Sessions follow a Propose -> Counter -> Accept/Reject lifecycle with configurable round limits and timeouts.

Lifecycle¶

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Countered: Counter-offer
    Countered --> Countered: Another counter
    Countered --> Accepted: Terms agreed
    Proposed --> Accepted: Terms agreed
    Proposed --> Rejected: Declined
    Countered --> Rejected: Max rounds or declined
    Accepted --> [*]
    Rejected --> [*]

Configuration¶

Agent Tools¶

Events¶

Escrow¶

The escrow service holds funds in a milestone-based escrow between buyer and seller. The escrow follows a structured lifecycle from creation through settlement, with support for dispute resolution.

Lifecycle¶

stateDiagram-v2
    [*] --> Created
    Created --> Funded: escrow_fund
    Funded --> Active: escrow_activate
    Active --> WorkSubmitted: escrow_submit_work
    WorkSubmitted --> Released: escrow_release
    Active --> Disputed: escrow_dispute
    Funded --> Disputed: escrow_dispute
    Disputed --> Resolved: escrow_resolve
    Active --> Refunded: escrow_refund
    Funded --> Refunded: escrow_refund

Configuration¶

Agent Tools¶

Events¶

On-Chain Escrow¶

When on-chain settlement is enabled, escrow operations are backed by Solidity smart contracts deployed on an EVM-compatible chain. Lango supports two on-chain modes:

Hub Mode¶

Uses a single LangoEscrowHub contract that holds multiple deals. All escrows share one contract address, reducing deployment costs. This is the default on-chain mode.

Vault Mode¶

Uses LangoVaultFactory to deploy a per-deal LangoVault via EIP-1167 minimal proxy (clone). Each escrow gets its own isolated contract instance, providing stronger separation of funds.

Hub V2¶

The HubV2Client provides typed access to the UUPS-upgradeable LangoEscrowHubV2 contract. It extends V1 with refId support (a [32]byte reference identifier for cross-system correlation) and new deal types.

Key methods:

On-chain deal types: Simple, Milestone, Team.

The V2 event monitor auto-detects V1 vs V2 events by topic count (V2 events have refId as an extra indexed parameter, giving them 4 topics instead of 3).

Source: internal/economy/escrow/hub/client_v2.go

Milestone Settler¶

The HubSettler implements SettlementExecutor using the LangoEscrowHub contract. It manages the full on-chain lifecycle:

• Lock -- Creates a deal on-chain and deposits funds. Maps buyerDID to the on-chain dealID for future operations.
• Release -- Releases funds to the seller by looking up the deal ID from the DID mapping.
• Refund -- Refunds funds to the buyer and removes the deal mapping.

The settler supports offline mode (NewHubSettlerOffline) where all on-chain operations become no-ops with warning logs, useful for testing.

Deal ID mappings can be set explicitly via SetDealMapping(escrowID, dealID) or SetDealMappingByDID(did, dealID) for integration with the team-escrow bridge.

Source: internal/economy/escrow/hub/hub_settler.go

Dangling Escrow Detector¶

The DanglingDetector is a lifecycle component that periodically scans for escrows stuck in Pending status longer than a configurable threshold. It auto-expires stale escrows and publishes an EscrowDanglingEvent.

Behavior:

1. Every scanInterval (default: 5m), query all escrows with StatusPending created before now - maxPending
2. For each dangling escrow, call engine.Expire() to transition it to expired
3. Publish EscrowDanglingEvent with escrow details and action: "expired"

Source: internal/economy/escrow/hub/dangling_detector.go

On-Chain Deal States¶

Created --> Deposited --> WorkSubmitted --> Released
                 |              |
             Disputed      Refunded
                 |
             Resolved

On-Chain Configuration¶

On-Chain Events¶

Smart Account Integration¶

When smart accounts are enabled (smartAccount.enabled), the economy layer integrates with three smart account components:

• On-Chain Spending Tracker — Tracks session key spending against budget limits. Budget alerts trigger when thresholds are crossed.
• Session Guard — The Security Sentinel can trigger emergency session key revocation when anomalies are detected (rapid creation, large withdrawal, repeated dispute).
• Risk Adapter — The risk engine feeds into the smart account policy engine, dynamically adjusting spending limits based on peer trust scores.

See Smart Accounts for full details.

Security Sentinel¶

The Security Sentinel monitors escrow activity for suspicious patterns and generates alerts. It runs as a background engine that analyzes escrow events in real time.

Detectors¶

Alert Severity¶

Alerts are categorized by severity: critical, high, medium, low.

Agent Tools¶

Events Summary¶

All economy events are published on the event bus:

Configuration¶

Settings: lango settings -> Economy

{
  "economy": {
    "enabled": true,
    "budget": {
      "defaultMax": "10.00",
      "alertThresholds": [0.5, 0.8, 0.95],
      "hardLimit": true
    },
    "risk": {
      "escrowThreshold": "5.00",
      "highTrustScore": 0.8,
      "mediumTrustScore": 0.5
    },
    "pricing": {
      "enabled": true,
      "trustDiscount": 0.1,
      "volumeDiscount": 0.05,
      "minPrice": "0.01"
    },
    "negotiate": {
      "enabled": true,
      "maxRounds": 5,
      "timeout": "5m",
      "autoNegotiate": false,
      "maxDiscount": 0.2
    },
    "escrow": {
      "enabled": true,
      "defaultTimeout": "24h",
      "maxMilestones": 10,
      "autoRelease": false,
      "disputeWindow": "1h",
      "settlement": {
        "receiptTimeout": "2m",
        "maxRetries": 3
      },
      "onChain": {
        "enabled": false,
        "mode": "hub",
        "hubAddress": "",
        "vaultFactoryAddress": "",
        "vaultImplementation": "",
        "arbitratorAddress": "",
        "tokenAddress": "",
        "pollInterval": "15s",
        "confirmationDepth": 2,
        "directSettlerAddress": "",
        "milestoneSettlerAddress": ""
      }
    }
  }
}

See the Economy CLI Reference for command documentation.