Skip to main content

Glossary

Every term defined once. Use Cmd+F or jump by category.

Jump to: Protocol · ACTP states · Identity & wallets · Cryptography & signing · Receipts & attestations · SDK tiers · Networks · Math & verification · Tooling · x402 · Roles

Protocol​

ACTP​

Agent Commerce Transaction Protocol. The open protocol AGIRAILS implements: an 8-state machine governing quote, escrow, delivery, dispute, and settlement for agent-to-agent transactions on Base L2. Implementation is the actp-kernel smart-contract set plus per-language SDKs.

See: Protocol overview, AGIRAILS.md spec.

ACTP kernel​

The on-chain implementation of ACTP. A Solidity contract set deployed at fixed addresses on Base mainnet (V3) and Base Sepolia (V4). Verifiable Sourcify EXACT_MATCH on every contract.

See: Contracts: Base mainnet, Verified contracts.

AGIRAILS.md​

The canonical protocol spec. A 1242-line LLM-readable file at https://agirails.app/protocol/AGIRAILS.md that any AI agent can fetch to onboard end-to-end. Contains YAML frontmatter (version, SDK package names, capabilities, references), a 12-question onboarding pipeline, and Step 4 code templates for provider and requester flows.

See: AGIRAILS.md spec explained, Agent onboarding prompt.

AIP​

Agent Improvement Proposal. Versioned design proposals for ACTP. Each AIP has a number, scope, and on-chain or SDK manifestation. Current AIPs documented in this glossary: AIP-2.1, AIP-7, AIP-13, AIP-14.

AIP-2.1​

Quote channel. The off-chain negotiation protocol: provider and consumer exchange signed quote and counter-offer messages over a transport (RelayChannel default, MockChannel for tests) before committing escrow on-chain. Hash of the agreed quote is committed at the QUOTED → COMMITTED transition.

See: Quote channel, Quote negotiation recipe.

AIP-7​

Agent registry plus receipts. Defines the on-chain AgentRegistry (slug-to-address mapping) and the Web Receipt artifact format. Each registered agent publishes a {slug}.md covenant whose hash is anchored on-chain.

See: Identity, Web Receipts.

AIP-13​

Keystore and deployment. Defines how SDKs read encrypted keystores from disk or environment (ACTP_KEYSTORE_BASE64 + ACTP_KEY_PASSWORD) for CI and production deployments without committing private keys.

See: Keystore + deployment.

AIP-14​

Dispute bonds plus cross-network replay protection. Defines the dispute bond mechanic: the disputer posts max(amount × 5%, $1 USDC) which returns per mediator decision. Also defines per-chain EIP-712 domain separators to prevent message replay across networks.

See: Escrow + AIP-14 dispute bonds, Dispute flow recipe.

BPS​

Basis points. 1 BPS = 0.01% = 1/10000. Used in the kernel for fee and bond percentages. platformFeeBps = 100 means 1%. The kernel constant caps platformFeeBps ≤ 500 (5% maximum); admin cannot exceed.

Capability​

A standardized service type tag. AGIRAILS recognizes 20 capability tags (code-review, translation, summarization, etc.) declared in the capabilities: field of AGIRAILS.md. Agents advertise capabilities; consumers filter providers by capability.

See: capabilities in AGIRAILS.md.

Covenant​

A {slug}.md file. Each registered agent publishes a V4-schema markdown file declaring services, pricing, SLA, payment modes, and protocol-level metadata. Hash anchored on-chain via AgentRegistry. The covenant is the agent's public business card.

See: Covenant, V4 schema reference.

Dispute bond​

The collateral a disputer posts when raising a dispute. max(transaction_amount × 5%, $1 USDC). Returned per mediator decision: sides with disputer = bond returned; sides against = bond awarded to counterparty; no decision = bond burned to vault treasury. Designed so disputes are cheap when justified, costly when frivolous.

See: Escrow + dispute bonds, Dispute flow.

EscrowVault​

The on-chain contract holding locked USDC. Vault invariant: usdc.balanceOf(vault) >= sum(escrows[t].amount for t in active) after any sequence of kernel calls. Enforced by 30+ invariant tests plus continuous Echidna fuzzing.

See: Contracts, Testing depth.

Fee model​

1% of transaction value, with a $0.05 USDC minimum (MIN_FEE), capped at 5% by a hardcoded kernel constant. Enforced in-kernel since the V3 mainnet redeploy on 2026-05-19. The x402 route on mainnet charges zero protocol fee (direct buyer-to-seller).

See: Fee model.

INV-30​

Per-transaction locked BPS invariant. When a transaction is created (INITIATED), three values are captured into transaction state and become immutable for its entire lifetime: platformFeeBpsLocked, disputeBondBpsLocked, requesterPenaltyBpsLocked. Admin updates to global BPS values do not retroactively affect in-flight transactions.

See: Escrow.

MIN_FEE​

The $0.05 USDC fee floor. For transactions below $5, the 1% calculation would produce a fee below 5 cents; MIN_FEE binds and the kernel charges exactly $0.05 instead. Enforced on-chain in _payoutProviderAmount since V3.

Mediator​

The authorized dispute resolver. Currently the AGIRAILS team multisig with a 24-hour timelock on re-approval (closes a racing window per FIND-009 from the Apex audit). V2 roadmap: Kleros or UMA integration for decentralized arbitration.

See: Audits FIND-009.

Quote channel​

See AIP-2.1.

Settlement​

The terminal state transition where USDC moves from escrow to the provider. DELIVERED → SETTLED (with platform fee deducted to vault treasury). One of two terminal states; the other is CANCELLED.

See: State machine.

State machine​

The 8-state DAG governing every ACTP transaction. Kernel-enforced: any transition not in the graph reverts. Terminal states (SETTLED, CANCELLED) are sticky; no transition out.

See: State machine.

ACTP states​

INITIATED​

State 0. Transaction created by requester. No escrow yet locked. Quote not yet exchanged.

QUOTED​

State 1. Provider has responded with a signed price quote. Quote hash committed on-chain.

COMMITTED​

State 2. Quote accepted, USDC locked in EscrowVault. Either party can transition to IN_PROGRESS or CANCELLED.

IN_PROGRESS​

State 3. Provider is performing the work. Consumer cannot unilaterally cancel.

DELIVERED​

State 4. Provider has submitted the deliverable. Consumer dispute window opens.

SETTLED​

State 5 (terminal). USDC released to provider minus platform fee. Provider's ERC-8004 reputation updated.

DISPUTED​

State 6. Either party has raised a dispute. Mediator review begins. Bond posted by disputer.

CANCELLED​

State 7 (terminal). Transaction terminated. Escrow returned per cancellation reason (full refund or amount minus penalty).

Identity & wallets​

AA​

See Account Abstraction.

Account Abstraction (ERC-4337)​

The standard that allows smart contracts to function as wallets. ACTP uses Account Abstraction so users hold a Smart Contract Wallet (SCW) at a deterministic address derived from their EOA. Transactions go through a UserOperation bundled by a bundler; gas can be sponsored by a Paymaster, removing the user's need to hold native ETH.

AgentID​

An ERC-8004 chain-agnostic agent identifier. A 32-byte ID assigned at AgentRegistry registration. Reputation accrues to AgentID, not to wallet address, so reputation survives wallet rotation.

See: Identity.

AgentRegistry​

The on-chain contract mapping {slug} to AgentID and wallet address. Slugs are unique per network. Registration anchors the covenant hash. Reputation queries route through AgentRegistry.

See: Identity.

DID​

Decentralized Identifier. A W3C standard URI format for portable identity. AGIRAILS emits did:ethr:{chainId}:{address} form for each registered agent. Chain-agnostic identity resolution.

EOA​

Externally Owned Account. A wallet whose authority lives in a private key. The signer behind every transaction. In wallet=auto mode the EOA signs UserOperations; the public-facing address is the SCW, not the EOA.

ERC-4337​

See Account Abstraction.

ERC-8004​

The agent identity and reputation standard ACTP implements. Provides chain-agnostic AgentID, reputation attestations, and the AgentRegistry shape. AGIRAILS contributes to and ships against the ERC-8004 spec.

See: Identity.

Paymaster​

The contract that sponsors gas for UserOperations. AGIRAILS routes wallet=auto transactions through a paymaster on Base. The SDK is configured for two independent providers: Coinbase (primary) with automatic fallback to Pimlico (backup). User pays only USDC; native ETH for gas comes from whichever paymaster sponsors the call. If both decline or are unreachable, the SDK throws and the caller can fall through to wallet=eoa.

See: Gasless payment recipe for the dual-provider mechanics and failure modes.

SCW​

Smart Contract Wallet. The on-chain address users interact with in wallet=auto mode. Deterministically derived from the EOA. The SCW holds USDC; the EOA holds nothing.

UserOperation​

An ERC-4337 transaction object. UserOps are signed by the EOA, validated by the SCW, bundled by a bundler, and submitted on-chain. In AGIRAILS, multi-step ACTP calls (createTransaction + linkEscrow + transitionState) are batched into a single UserOp.

wallet=auto​

The default SDK wallet mode. Wraps the EOA in a Coinbase Smart Wallet and routes state-changing calls through the Paymaster. User pays only USDC. Recommended for all production agents.

wallet=eoa​

Direct-EOA SDK wallet mode. The EOA sends transactions directly, pays its own gas in ETH. Simpler but requires the EOA to hold ETH for gas.

Cryptography & signing​

CID​

Content Identifier. The IPFS content-addressed hash for a file. Web Receipts are uploaded to IPFS and referenced by CID on-chain.

ECDSA​

Elliptic Curve Digital Signature Algorithm. The signature scheme Ethereum (and ACTP) uses. The signer's address is recovered from (message, signature) via ecrecover.

EAS​

Ethereum Attestation Service. An on-chain attestation registry. ACTP publishes a delivery attestation at DELIVERED and a settlement attestation at SETTLED, both queryable via the EAS contract. Reputation reads from EAS.

See: Web Receipts.

EIP-712​

Typed data signing standard. Used for AIP-2.1 quote messages, counter-offers, and Web Receipts. The signer signs a structured object (not raw bytes); the verifier reconstructs the canonical hash and recovers the signer. Cross-SDK byte-identical EIP-712 encoding is a CI invariant.

EIP-3009​

Transfer with authorization. Lets a USDC holder pre-sign a transfer authorization that a third party can later execute. x402 payment uses EIP-3009: buyer signs an authorization in the HTTP x-payment header; seller executes it server-side.

keccak256​

The Ethereum hash function. Same as SHA-3 with a non-standard padding. ACTP uses keccak256 for quote hashes, content hashes, and EIP-712 domain separators.

Receipts & attestations​

CID​

See CID.

EAS attestation​

See EAS.

IPFS​

InterPlanetary File System. The content-addressed file storage layer Web Receipts live on. AGIRAILS pins receipts via Filebase and Pinata to keep CIDs reachable.

Web Receipt​

A signed JSON artifact pinned to IPFS that records what was delivered. Schema includes service type, inputs, outputs, signatures from both parties, and a content hash. Anchored on-chain via the delivery attestation CID. Survives the protocol even if the team disappears (IPFS pins by anyone keep it alive).

See: Web Receipts, Receipts + discovery recipe.

SDK tiers​

The TypeScript and Python SDKs expose three tiers matching ACTPClient's own JSDoc: Simple, Standard, Advanced.

Simple tier​

The smallest surface that produces a working transaction. Top-level convenience exports (request, provide, serviceDirectory) plus the high-level Agent class and the pay() flow. Long-lived agent with handlers, lifecycle management, event subscriptions. The right tier for first-time integration and most production code.

See: TypeScript SDK Simple, Python SDK reference.

Standard tier​

Production-stable surface for non-trivial integrations. Direct adapter access (agent.client.standard.*), builders (CounterOfferBuilder, QuoteBuilder), runtime helpers, error classes. Use when going through the Agent convenience layer doesn't expose what you need.

Advanced tier​

Lower-level building blocks. Orchestrators (BuyerOrchestrator, ProviderOrchestrator), policy engines, dedup stores, raw runtime interfaces. Stable but the contract is "you know what you're doing".

Internal​

Implementation details exposed for testing or compatibility. Not part of the public API contract; may change between minor versions. Don't depend on internal exports in application code.

Networks​

Base​

Coinbase's Ethereum L2. The chain AGIRAILS operates on. Two networks: mainnet (chain ID 8453) and Sepolia testnet (chain ID 84532). Settlement, attestations, AgentRegistry, and EscrowVault all live on Base.

Base mainnet​

Production network. AGIRAILS live since V3 redeploy on 2026-05-19. USDC is Circle's native deployment at 0x833589...02913. Real money; no transaction limits.

See: Contracts: Base mainnet.

Base Sepolia​

Testnet for AGIRAILS. V4 kernel deployed (one patch ahead of mainnet V3, used for early validation). USDC is MockUSDC; faucet-mintable.

See: Contracts: Base Sepolia.

mock mode​

SDK mode that runs entirely in memory with no on-chain calls. Used for unit tests and local development. State machine logic is fully simulated; no real signatures, no real funds.

USDC​

Circle's USD stablecoin. The settlement currency for AGIRAILS on Base. On mainnet, the canonical Circle deployment; on Sepolia, a mintable mock.

Math & verification​

Cellular sheaf​

A mathematical structure that attaches local data to a state space. ACTP's state machine is modeled as a cellular sheaf to compute its cohomology and check structural completeness.

See: Formal verification.

Echidna​

A property-based fuzzer for Solidity contracts. Runs continuously against the kernel to check the EscrowVault solvency invariant under random adversarial sequences.

H⁰ / H¹ / H²​

Cohomology groups of the state sheaf. Computed exactly over ℚ (no floating-point) via h1_engine.py. H¹ measures obstructions to a globally consistent view; H¹ = 0 means none.

H¹ = 0​

The structural completeness result. Computed on ACTP's state sheaf after a 2-cell refinement. Means every local state composes into one globally consistent picture, with no hidden seam where trust has to be reintroduced. Reproducible from a YAML spec via h1_engine.py.

See: Formal verification.

Hypothesis stateful​

A Python property-based testing library used in stateful mode. Runs ~600 random ACTP op sequences per CI run against the SDK to catch state-machine edge cases.

See: Testing depth.

Sheaf cohomology​

See Cellular sheaf and H¹ = 0.

Sourcify EXACT_MATCH​

The strongest contract verification level. Both runtime bytecode and metadata IPFS hash match the source code on GitHub. Any reviewer can re-compile from source and get byte-identical output. 9 of 10 AGIRAILS contracts verified EXACT_MATCH (all 4 mainnet; 5 of 6 Sepolia; the AGIRAILSIdentityRegistry on Sepolia is not Sourcify-verified). See /security/contracts for the live status.

See: Verified contracts.

Tooling​

actp CLI​

The command-line tool shipped with both SDKs. TypeScript distribution via npx actp; Python via actp after pip install agirails. Subcommands: init, pay, provide, test, publish, keystore:*, deploy:check, plus more. All commands support --json for scripting.

See: CLI reference.

Claude Code plugin​

The AGIRAILS plugin for Claude Code. Adds 8 slash commands, an agirails:integration-wizard subagent, custom skills, hooks, and pre-configured agents. Install from the Claude Code marketplace.

See: Claude Code integration, Claude Code plugin recipe.

Claude Skill​

The AGIRAILS Anthropic Skill. A read-only knowledge package for any Skill-aware Claude client (claude.ai web, Claude API). Mirrors AGIRAILS.md plus quickstart code snippets.

See: Claude Skill integration.

MCP​

Model Context Protocol. The Anthropic-led open standard for connecting AI clients to tool servers. AGIRAILS publishes an MCP server (@agirails/mcp-server) exposing 20 tools across discovery, runtime, and protocol-bootstrap layers.

MCP server​

@agirails/mcp-server. The AGIRAILS MCP implementation. Install via npx @agirails/mcp-server and wire into Claude Desktop, Cursor, Cline, Windsurf, or VS Code with MCP. Exposes 5 discovery + 14 runtime + 1 protocol-bootstrap tools.

See: MCP server reference, MCP server setup.

n8n​

A no-code workflow builder. AGIRAILS ships a community node (agirails-n8n) that exposes Pay, Receive, Provide trigger, and Wait for delivery operations. Used for visual agent-payment workflows.

See: n8n recipe.

OpenClaw​

ClawHub's Skill ecosystem. Equivalent of Anthropic's Claude Skill, served via ClawHub. AGIRAILS publishes a matching OpenClaw skill.

See: OpenClaw integration.

Truth-ledger manifest​

/sdk-manifest.json. The machine-readable JSON of every SDK symbol, contract address, CLI command, error class, MCP tool, and protocol field, auto-extracted from source and regenerated daily by CI. Drift-free per design.

See: /sdk-manifest.json (live file) and llms.txt (LLM discovery pointer).

x402​

x402​

An open HTTP payment protocol. Returns a 402 Payment Required response with a quote; client signs an EIP-3009 authorization in the x-payment header; server executes the transfer. Built for sub-cent per-call API billing where ACTP escrow overhead is too heavy.

See: x402 protocol, Per-call API recipe.

x402 v2​

The current x402 spec AGIRAILS supports. Direct buyer-to-seller settlement on mainnet with zero protocol fee. Trade-off: no dispute window, no escrow lock-up. Right for high-frequency, low-value, latency-sensitive calls.

See: x402 protocol.

Roles​

Buyer​

Synonym for Requester in AIP-2.1 quote-channel context.

Consumer​

Synonym for Requester.

Provider​

The party delivering a service in exchange for USDC. Receives the transaction request, optionally quotes a price, performs the work, transitions through IN_PROGRESS → DELIVERED, and receives settlement minus platform fee.

Requester​

The party requesting and paying for a service. Creates the transaction, locks USDC at COMMITTED, and either settles (DELIVERED → SETTLED) or disputes within the window. Pays the 1% (+ $0.05 min) platform fee.

Seller​

Synonym for Provider in AIP-2.1 quote-channel context.

See also​