Receipts

What is a receipt?

A receipt is a cryptographically signed, gateway-issued document that records the outcome of a policy guard request. It is the trust artifact of the AgentChain system — independently verifiable without a network call.

Receipt lifecycle

State	Terminal?	Meaning
`issued`	No	Guard evaluated, decision signed, awaiting client execution
`executed`	No	Client reported `txHash` via `reportExecution()`
`anchored`	Yes	`receiptHash` written on-chain to `ReceiptAnchor`
`denied`	Yes	Policy rejected — no execution possible
`approval_required`	No	Held in approval queue pending operator decision
`expired`	Yes	`decisionExpiresAt` passed before execution was reported

Receipt fields

type EvmGuardReceiptV2 = {
  receiptId: string;           // UUID
  state: 'issued' | 'executed' | 'denied' | 'approval_required' | 'expired' | 'anchored';
  decision: 'allow' | 'deny' | 'approval_required';

  // Policy binding
  policyId: string;
  chainId: number;
  policyHash: string;          // keccak256(JCS(policy body at version))
  policyVersion: number;
  policySource: 'gateway' | 'anchored' | 'onchain_registry';

  // Transaction intent (what was guarded)
  from: string;
  to: string;
  data: string;
  value: string;
  calldataHash: string;        // keccak256(data)
  simulationHash: string;      // keccak256(blockNum + returnData) — ZERO_B32 in MVP

  // Timing
  issuedAt: string;            // ISO 8601
  decisionExpiresAt: string;   // ISO 8601 — MUST send before this (default: issuedAt + 300s)
  receiptExpiresAt: string;    // ISO 8601 (0 = never)

  // Signature (EIP-712)
  receiptHash: string;         // EIP-712 typed data digest
  signature: string;           // 65-byte ECDSA (hex)
  signerAddress: string;       // recovering address
  signerKeyId: string;         // key rotation handle

  // Deny / approval
  reasonCodes: string[];       // e.g. ['VALUE_EXCEEDED']
  approvalId: string | null;   // present when decision = approval_required

  // Execution (filled after reportExecution)
  executionTxHash: string | null;  // self-reported — NOT covered by ECDSA signature (see below)
  executionChainId: number | null;
  executionReportedAt: string | null;

  // Anchor (filled after on-chain anchoring)
  anchorTxHash: string | null; // tx that wrote receiptHash to ReceiptAnchor
};

Verifier Note — executionTxHash is self-reported The EIP-712 ECDSA signature covers the receipt body at issue time, when executionTxHash = bytes32(0). After reportExecution(), the executionTxHash field is updated in the database but the original signature is not re-issued. Verifiers must use the original receiptHash (computed at issue time) for ECDSA verification — not a re-hashed post-execution body.

Deny Receipts are Signed deny and approval_required receipts are signed with the same ECDSA key as allow receipts. A signed deny receipt is a tamper-evident proof that the system evaluated and blocked the transaction. The decision field is included in the signed EIP-712 struct — it cannot be altered.

Signature scheme

Receipts are signed with EIP-712 (keccak256(0x1901 ‖ domainSeparator ‖ structHash)).

const ReceiptDomain = {
  name: "AgentChain Receipt",
  version: "2",
  chainId: <number>,                        // chain the receipt authorizes
  verifyingContract: "0x36cbAE566545e8df3ad15C171a7840266526E28F", // SignerAnchor (Base Sepolia)
};

The chainId in the domain separator binds the signature to a specific chain. A receipt signed for Base Sepolia (84532) cannot be replayed on Base mainnet (8453) — the domain hash will differ.

Local verification (no network)

import { AgentChain } from '@humbleaf/agentchain-sdk';

const ac = new AgentChain({ apiKey: '...' });
const valid = ac.receipts.verify(
  receipt.receiptHash as `0x${string}`,
  receipt.signature as `0x${string}`,
  receipt.signerAddress as `0x${string}`,
);

Uses @agentchain/core verifyReceiptSignature — pure ECDSA recover, no HTTP.

On-chain verification (trustless)

const ac = new AgentChain({
  apiKey: '...',
  signerAnchorAddress: '0x36cbAE566545e8df3ad15C171a7840266526E28F',
  signerAnchorChainId: 84532,
  signerAnchorRpcUrl: 'https://sepolia.base.org',
});

const result = await ac.receipts.verifyWithAnchor(receipt);

verifyWithAnchor performs two independent checks:

ECDSA verify — signerAddress correctly recovers from receiptHash + signature
On-chain check — SignerAnchor.isAuthorized(signerAddress) returns true

// VerifyReceiptResult — discriminated union on valid + onChainVerified
type VerifyReceiptResult =
  | { valid: true;  onChainVerified: true  }                         // ECDSA + on-chain: fully trustless
  | { valid: true;  onChainVerified: false; reasons: string[] }      // ECDSA ok, on-chain degraded
  | { valid: false; onChainVerified: boolean; reasons: string[] };   // ECDSA failed

// reasons include: 'signature_mismatch' | 'signer_revoked' | 'signer_anchor_unavailable' | 'signer_anchor_rpc_error'

The SDK degrades gracefully (IC-30): if the RPC call fails, anchorState is 'unavailable' and ECDSA verification alone is used. Never a silent pass.

Remote verification

const result = await ac.receipts.verifyRemote(receipt);
if (!result.valid) {
  console.error('Invalid:', result.reasons);
}

The gateway checks signature, expiry, state, and SignerAnchor revocation status.

Fetch by ID

const stored = await ac.receipts.get(receiptId);

Report execution

After guardTransaction returns allow, call this after you send the transaction:

const updated = await ac.evm.reportExecution(receipt.receiptId, txHash);
// updated.state === 'executed'

guardAndExecute calls this automatically.

`decisionExpiresAt`

The gateway sets decisionExpiresAt to issuedAt + 300s (configurable). If your execution logic takes more than 5 minutes, call guardTransaction again for a fresh receipt. The SDK throws AgentChainExpiredDecision if decisionExpiresAt < now when guardAndExecute tries to send.

Policy revocation and the 5-minute window A receipt issued just before a policy is revoked remains valid for up to 300 seconds (5 minutes). This is by design — in-flight, already-authorized transactions must be allowed to complete. After decisionExpiresAt, reportExecution returns 410 DECISION_EXPIRED. The window cannot be shortened without breaking in-flight transactions.

Anchoring

When a policy has anchoring = "receipt_hash_onchain", the gateway’s ReceiptAnchorJob batch-writes the receiptHash to ReceiptAnchor.sol on the declared chain. The receipt transitions from executed → anchored after 2 confirmations. ReceiptAnchor on Base Sepolia: 0x1F98D953785047f25a4886D12D103F4D67F1D8B3

// Poll anchor status
const status = await ac.receipts.getAnchorStatus(receiptId);
// status.state — 'pending' | 'anchored'
// status.anchorTxHash — string | null

Getting Started

Core Protocol

Infrastructure

What is a receipt?

Receipt lifecycle

Receipt fields

Signature scheme

Local verification (no network)

On-chain verification (trustless)

Remote verification

Fetch by ID

Report execution

`decisionExpiresAt`

Anchoring

​What is a receipt?

​Receipt lifecycle

​Receipt fields

​Signature scheme

​Local verification (no network)

​On-chain verification (trustless)

​Remote verification

​Fetch by ID

​Report execution

​decisionExpiresAt

​Anchoring

What is a receipt?

Receipt lifecycle

Receipt fields

Signature scheme

Local verification (no network)

On-chain verification (trustless)

Remote verification

Fetch by ID

Report execution

`decisionExpiresAt`

Anchoring