@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/reference/quantu-agent-registry.mdx

@@ -1,15 +1,110 @@
 ---
-title: Quantu Agent Registry
-description: Quantu ERC-8004 accounts and feedback CPI used by AgentTrust.
+title: Quantu agent registry
+description: The Quantu CPI surface AgentTrust consumes — give_feedback discriminator, AgentAccount + AtomStats accounts, byte-offset reads, pinned commit.
 ---
 
-`In progress`
+AgentTrust reads two Quantu programs from `8004-solana`:
 
-TrustGate emits feedback through Quantu `agent-registry-8004::give_feedback`, while PolicyVault reads Quantu AtomStats for counterparty policy checks.
+- `agent-registry-8004` — agent identity + the `give_feedback` instruction TrustGate CPIs into.
+- `atom-engine` — confidence-weighted reputation aggregation. `AtomStats` PDA carries the `tier_immediate` byte PolicyVault gates against.
 
-| Surface | Source |
-| --- | --- |
-| feedback CPI | [`programs/trustgate/src/ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs) |
-| AtomStats parser | [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs) |
-| research notes | [`docs/plan/research/02-quantu-erc8004-archaeology.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/plan/research/02-quantu-erc8004-archaeology.md) |
+Both pinned to commit `bfb09ad`.
 
+## `give_feedback` CPI
+
+Discriminator: `[145, 136, 123, 3, 215, 165, 98, 41]`.
+
+```rust
+pub struct GiveFeedbackArgs {
+    pub value: u64,
+    pub value_decimals: u8,
+    pub score: Option<u8>,                      // 0..=100
+    pub feedback_file_hash: Option<[u8; 32]>,   // dispute_reason_hash for disputes
+    pub tag1: String,                           // ≤ 32 bytes
+    pub tag2: String,                           // ≤ 32 bytes
+    pub endpoint: String,                       // ≤ 64 bytes
+    pub feedback_uri: String,                   // ≤ 256 bytes
+}
+```
+
+`remaining_accounts` ordering for the CPI:
+
+| Index | Account | Notes |
+|---:|---|---|
+| 0 | `agent_account` | payee's `AgentAccount` PDA |
+| 1 | `asset` | payee's Metaplex Core asset |
+| 2 | `collection` | Quantu's collection asset |
+| 3 | `system_program` | for AtomStats init rent |
+| 4 | `atom_config` (optional) | Quantu's `AtomConfig` PDA |
+| 5 | `atom_stats` (optional) | payee's `AtomStats` PDA |
+| 6 | `atom_engine_program` (optional) | Quantu's `atom-engine` |
+| 7 | `registry_authority` (optional) | Quantu's registry authority PDA |
+
+Indexes 0..=3 are required; 4..=7 come as a group of 4 (all four or none). TrustGate's `emit_feedback` handler validates this in [`programs/trustgate/src/instructions/emit_feedback.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/instructions/emit_feedback.rs).
+
+The SDK's [`deriveQuantuFeedbackAccounts`](/sdk/exports-reference#quantu-helpers) returns this account bundle correctly ordered.
+
+## `AtomStats` byte-offset reads
+
+PolicyVault's [CounterpartyTier](/programs/policy-vault/counterparty-tier-policy) policy reads `AtomStats` via a manual byte-offset parser pinned to commit `bfb09ad`. Schema-version canary at byte 560 catches drift.
+
+| Offset | Width | Field |
+|---:|---:|---|
+| 549 | u8 | `risk_score` |
+| 551 | u8 | `tier_immediate` (v1 demo default) |
+| 555 | u8 | `tier_confirmed` (production) |
+| 557 | u16 LE | `confidence` (basis points) |
+| 560 | u8 | `schema_version` (must equal 1) |
+
+Account size: 561 bytes. Tier domain: `0..=4` (`ATOM_TIER_MAX = 4`).
+
+Full table: [Reference → Byte offsets](/reference/byte-offset-reference).
+
+## Mainnet vs devnet program IDs
+
+| Program | Mainnet | Devnet |
+|---|---|---|
+| `agent-registry-8004` | `8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ` | `8oo4J9tBB3Hna1jRQ3rWvJjojqM5DYTDJo5cejUuJy3C` |
+| `atom-engine` | `AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb` | `AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF` |
+
+The SDK's `MAINNET_QUANTU_IDS` and `DEFAULT_DEVNET_QUANTU_IDS` carry these. `NETWORK` env on the MCP server drives the right pair: [MCP → Install](/mcp/install).
+
+## Why byte-offset and not Borsh?
+
+Two reasons:
+
+1. **Zero Cargo dep on Quantu's crate.** AgentTrust would otherwise pin to Quantu's published Anchor IDL or workspace package. A Quantu version bump that re-orders fields would silently change PolicyVault's reads through Borsh's positional encoding. The byte-offset parser is fragile against layout changes — but fragile-with-canary, not fragile-silent. The `schema_version` byte at 560 fails loud rather than silently misread.
+2. **Bounded compute.** Borsh deserialization allocates and walks the full struct. The byte-offset parser reads exactly the five bytes PolicyVault gates against — `risk_score`, `tier_immediate`, `tier_confirmed`, `confidence`, `schema_version`. Cheaper compute units, smaller stack frame.
+
+Trade-off: the parser must be re-pinned manually if Quantu bumps its layout. The pinned-commit comment in [`policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs) documents the bump procedure.
+
+## TrustGate's CPI wrapper
+
+TrustGate's `emit_feedback` PDA-signs the CPI:
+
+```rust
+let signer_seeds: &[&[u8]] = &[
+    TrustGateAuthority::SEED_PREFIX,    // b"trustgate_auth"
+    facilitator.as_ref(),
+    &[bump],
+];
+invoke_give_feedback(&cpi_accounts, &args, signer_seeds)?;
+```
+
+Quantu's `give_feedback` instruction expects the caller to be the agent's owner. TrustGate's PDA is registered as the feedback authority via Quantu's identity flow on first use (the `set_agent_wallet` instruction at `identity/instructions.rs:506-541` in Quantu's source). The `client` account in the CPI is set to `authority.to_account_info()`, so Quantu sees a PDA-signed call rather than the facilitator's wallet directly.
+
+CPI source: [`programs/trustgate/src/ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs).
+
+## Read next
+
+<Cards>
+  <Card title="TrustGate" href="/programs/trustgate">
+    The program that owns the CPI.
+  </Card>
+  <Card title="CounterpartyTier policy" href="/programs/policy-vault/counterparty-tier-policy">
+    What consumes the AtomStats reads.
+  </Card>
+  <Card title="Byte-offset reference" href="/reference/byte-offset-reference">
+    Per-account byte-offset tables.
+  </Card>
+</Cards>

package/dist/embedded-docs/sdk/exports-reference.mdx

@@ -0,0 +1,239 @@
+---
+title: Exports reference
+description: Every public export from @agenttrust-sdk/trustgate, grouped by concern.
+---
+
+The SDK ships three import surfaces. The `/express` and `/client` subpaths are tree-shake-friendly entry points; the root namespace re-exports everything else.
+
+```ts
+import { mountTrustGate }                   from "@agenttrust-sdk/trustgate/express";
+import { gatePayment, settle, dispute }     from "@agenttrust-sdk/trustgate/client";
+import { /* everything else */ }            from "@agenttrust-sdk/trustgate";
+```
+
+Source: [`trustgate/sdk/src/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/index.ts).
+
+## Atomicity guard
+
+```ts
+import {
+  AtomicityEnforced,
+  AtomicityNotEnforcedError,
+  assertAtomicityEnforced,
+  composeAtomicSettleTx,
+  deriveStandardAta,
+} from "@agenttrust-sdk/trustgate";
+```
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `AtomicityEnforced` | type | `{ atomicityEnforced: true }` literal-type marker |
+| `AtomicityNotEnforcedError` | class | thrown by runtime guard on non-`true` value |
+| `assertAtomicityEnforced(cfg, siteName)` | fn | runtime check; call at top of every settle/dispute entry point |
+| `composeAtomicSettleTx(args)` | async fn | builds a 3-ix `Transaction` (gate strict + transferChecked + emit_feedback) |
+| `deriveStandardAta(owner, mint, tokenProgram?)` | fn | standard ATA helper |
+| `AtomicSettleQuantuAccounts` | type | the Quantu account bundle `composeAtomicSettleTx` threads through `remaining_accounts` |
+| `ComposeAtomicSettleArgs` | type | full arg shape, `extends AtomicityEnforced` |
+| `ComposedAtomicSettle` | type | return shape: `{ tx, instructions, accounts }` |
+
+Source: [`trustgate/sdk/src/atomicity.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/atomicity.ts).
+
+## SPL helpers
+
+```ts
+import {
+  TOKEN_PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  buildTransferCheckedIx,
+  deriveAssociatedTokenAddress,
+} from "@agenttrust-sdk/trustgate";
+```
+
+`buildTransferCheckedIx` accepts an optional `tokenProgram` to switch between legacy SPL and Token-2022. The atomic-tx invariant applies to both — Token-2022's `TransferHook` extension is the canonical corruption vector that motivates the invariant; legacy SPL's `MissingRequiredSignature` revert produces the same atomicity behaviour.
+
+Source: [`trustgate/sdk/src/spl.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/spl.ts).
+
+## On-chain validator factory
+
+```ts
+import {
+  makeValidateOnChainTx,
+  type OnChainTxValidation,
+  type OnChainTxRejection,
+  type ValidateOnChainTxFn,
+  type MakeValidateOnChainTxOptions,
+} from "@agenttrust-sdk/trustgate";
+```
+
+`makeValidateOnChainTx({ connection, … })` returns a function the facilitator's `/settle` route plugs into the adapter's `validatePaymentProof` slot. Parses a confirmed SPL transfer transaction from RPC, cross-checks amount / mint / recipient / authority against the verify-time `VerifyContext`, and rejects mismatches with typed errors.
+
+Source: [`trustgate/sdk/src/onchain-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/onchain-validator.ts).
+
+## Quantu helpers
+
+```ts
+import {
+  DEFAULT_DEVNET_QUANTU_IDS,
+  MAINNET_QUANTU_IDS,
+  type QuantuProgramIds,
+  type QuantuFeedbackAccounts,
+  type QuantuFeedbackAccountsArgs,
+  deriveAgentAccountPda,
+  deriveAtomConfigPda,
+  deriveAtomStatsPda,
+  deriveAtomRegistryAuthorityPda,
+  deriveQuantuFeedbackAccounts,
+} from "@agenttrust-sdk/trustgate";
+```
+
+The `Quantu*` helpers derive Quantu PDAs without depending on Quantu's TypeScript package. Pinned to commit `bfb09ad` per [Reference → Mainnet program IDs](/reference/mainnet-program-ids). `deriveQuantuFeedbackAccounts` returns the full account bundle the `give_feedback` CPI needs in `remaining_accounts` order.
+
+Source: [`trustgate/sdk/src/quantu.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/quantu.ts).
+
+## emit_feedback factory
+
+```ts
+import {
+  makeEmitFeedbackCpi,
+  makePriorEmissionLookup,
+  type EmitFeedbackCpiFn,
+  type EmitFeedbackCpiInput,
+  type EmitFeedbackResult,
+  type MakeEmitFeedbackCpiOptions,
+  type PriorEmissionLookupFn,
+  type PriorEmissionResult,
+  type MakePriorEmissionLookupOptions,
+} from "@agenttrust-sdk/trustgate";
+```
+
+`makeEmitFeedbackCpi({ connection, … })` returns the function adapters plug into their `emitFeedback` slot. `makePriorEmissionLookup({ connection, … })` returns the `priorEmissionLookup` function — looks up `FeedbackEmissionLog` by `payment_id_hash` so retries return a stable receipt instead of double-emitting.
+
+Source: [`trustgate/sdk/src/emit-feedback.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/emit-feedback.ts).
+
+## ValidationRegistry
+
+```ts
+import {
+  VALIDATION_REGISTRY_DEVNET_ID,
+  deriveCapabilityNamespacePda,
+  deriveAttestorProfilePda,
+  deriveValidationRequestPda,
+  deriveValidationAttestationPda,
+  computeNamespaceHash,
+  computeCapabilityHash,
+  loadValidationRegistry,
+  buildRegisterNamespaceIx,
+  buildRegisterAttestorIx,
+  buildRequestValidationIx,
+  buildRespondToValidationIx,
+  buildRevokeValidationIx,
+  fetchValidationAttestation,
+  fetchValidationRequest,
+  fetchAttestorProfile,
+  fetchCapabilityNamespace,
+  type BuildRegisterNamespaceArgs,
+  type BuildRegisterAttestorArgs,
+  type BuildRequestValidationArgs,
+  type BuildRespondToValidationArgs,
+  type BuildRevokeValidationArgs,
+} from "@agenttrust-sdk/trustgate";
+```
+
+Full instruction-builder set for the third leg of ERC-8004. `computeCapabilityHash(name)` returns `SHA-256(name)`; `computeNamespaceHash(name)` is an alias kept for clarity. `fetch*` helpers return decoded views of each PDA.
+
+Source: [`trustgate/sdk/src/validation-registry.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/validation-registry.ts).
+
+## PDA derivers + Anchor loaders
+
+```ts
+import {
+  derivePolicyPda,
+  deriveVelocityPda,
+  deriveKillSwitchPda,
+  deriveFeedbackLogPda,
+  deriveTrustGateAuthorityPda,
+  loadPolicyVault,
+  loadTrustGate,
+  makeProvider,
+  simulateGatePayment,
+  parseGateDecision,
+} from "@agenttrust-sdk/trustgate";
+```
+
+`load*` helpers fetch the IDL from chain by default (`anchor idl fetch <programId>`). Pass an explicit `idl` argument to use a bundled snapshot — useful for latency-sensitive paths or freshly redeployed programs before `anchor idl upgrade`.
+
+Source: [`trustgate/sdk/src/chain.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/chain.ts).
+
+## x402 headers
+
+```ts
+import {
+  buildHeadersForDecision,
+  denyReasonName,
+  X_PAYMENT_REQUIRED,
+  X_PAYMENT_NETWORK,
+  X_PAYMENT_REASON_CODE,
+  X_PAYMENT_REASON_NAME,
+  X_CAPABILITY_REQUIRED,
+  X_AGENT_TRUST_DECISION,
+} from "@agenttrust-sdk/trustgate";
+```
+
+`buildHeadersForDecision(decision, network)` returns the header map for `Allow` / `Deny` / `RequireValidation`. `denyReasonName(code)` maps `1..=15` to the canonical name (e.g., `6` → `CounterpartyTierBelowMin`).
+
+Source: [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts).
+
+## Types + constants
+
+```ts
+import {
+  GateDecision,
+  DenyReasonCode,
+  ProgramIds,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+} from "@agenttrust-sdk/trustgate";
+```
+
+```ts
+type GateDecision =
+  | { kind: "Allow" }
+  | { kind: "Deny";              reasonCode: DenyReasonCode; reasonName: string }
+  | { kind: "RequireValidation"; capabilityHash: Uint8Array };
+
+interface ProgramIds {
+  policyVault:        PublicKey;
+  trustGate:          PublicKey;  // camelCase as of 0.2.0
+  validationRegistry: PublicKey;  // new in 0.2.0
+}
+```
+
+`DEFAULT_DEVNET_PROGRAM_IDS` carries the deployed-devnet IDs. Override via `ProgramIds` for mainnet redeploys. Source: [`trustgate/sdk/src/types.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/types.ts).
+
+## Express + client subpaths
+
+These have their own dedicated entry points and don't re-export through the root namespace:
+
+```ts
+// Express middleware (peer dep: express ^4.21)
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+
+// Client helpers
+import { gatePayment, settle, dispute } from "@agenttrust-sdk/trustgate/client";
+```
+
+References: [mountTrustGate](/sdk/mount-trustgate), [gatePayment](/sdk/gate-payment).
+
+## Read next
+
+<Cards>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Three layers of proof + the on-chain Kani strict-correctness binding.
+  </Card>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    Canonical FacilitatorAdapter implementation, end to end.
+  </Card>
+  <Card title="MCP server" href="/mcp">
+    Eighteen tools that surface every SDK helper to Claude Desktop and Cursor.
+  </Card>
+</Cards>

package/dist/embedded-docs/sdk/gate-payment.mdx

@@ -1,22 +1,107 @@
 ---
 title: gatePayment
-description: Read-only policy decision call for facilitators.
+description: Read-only policy decision call. Simulates PolicyVault's gate_payment instruction and returns the typed GateDecision union.
 ---
 
-`In progress`
+`gatePayment()` is the read-only entry point. It builds an Anchor simulation of `gate_payment`, parses the return-data channel into the TypeScript union, and never sends a transaction.
 
-`gatePayment()` simulates PolicyVault and returns `Allow`, `Deny`, or `RequireValidation`. It remains useful when a service already owns its x402 routing layer and only wants the AgentTrust decision.
+Use it when your facilitator already owns its x402 routing and only needs the AgentTrust decision. For atomic settlement (gate + transfer + feedback in one tx), use [`mountTrustGate`](/sdk/mount-trustgate) or [`composeAtomicSettleTx`](/sdk/exports-reference).
 
-For Pay.sh, the adapter path wraps this lower-level decision in:
+Source: [`trustgate/sdk/src/client.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/client.ts).
 
-1. x402 challenge parsing
-2. SERVICE signature verification
-3. proof validation
-4. feedback emission
+## Signature
 
-| Source | Path |
-| --- | --- |
-| SDK client | [`trustgate/sdk/src/client.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/client.ts) |
-| Pay.sh adapter | [`trustgate/server/src/facilitators/pay-sh/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/index.ts) |
-| shared types | [`trustgate/sdk/src/types.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/types.ts) |
-| package README | [`trustgate/sdk/README.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/README.md) |
+```ts
+import { gatePayment } from "@agenttrust-sdk/trustgate/client";
+
+export function gatePayment(req: GatePaymentRequest): Promise<GateDecision>;
+```
+
+## `GatePaymentRequest`
+
+```ts
+interface GatePaymentRequest {
+  rpcUrl:          string;
+  caller:          Keypair;     // facilitator keypair (signs simulate-tx)
+  payerAgentAsset: PublicKey;   // payer's Metaplex Core asset (Quantu agent identity)
+  payeeAgentAsset: PublicKey;   // payee's Metaplex Core asset
+  amount:          bigint | number;  // base units (1_000_000n = 1 USDC at 6 decimals)
+  mint:            PublicKey;   // USDC devnet: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+  policyId:        number;      // PolicyAccount.policy_id (u32)
+  programIds?:     ProgramIds;  // defaults to DEFAULT_DEVNET_PROGRAM_IDS
+}
+```
+
+The `caller` keypair signs the simulation transaction; the result is never committed, so the keypair is only used to satisfy the simulate-tx fee-payer. Pass any funded devnet keypair.
+
+## `GateDecision`
+
+```ts
+type GateDecision =
+  | { kind: "Allow" }
+  | { kind: "Deny";              reasonCode: number; reasonName: string }
+  | { kind: "RequireValidation"; capabilityHash: Uint8Array /* 32 bytes */ };
+```
+
+| Decision | Next step |
+|---|---|
+| `Allow` | Proceed to settlement (build / sign / submit the atomic tx). |
+| `Deny` | Return 402 to the user with `reasonName`. Surface `reasonCode` for machine consumers. |
+| `RequireValidation` | Route the user to the attestation flow for `capabilityHash`. After the attestor responds, re-call `gatePayment` — the gate now sees the new `ValidationAttestation` and flips to `Allow`. |
+
+`reasonCode` is decoupled from Borsh wire-format ordering. Full table: [Reference → DenyReason codes](/reference/deny-reason-codes).
+
+## Example
+
+```ts
+import { Keypair, PublicKey } from "@solana/web3.js";
+import { gatePayment } from "@agenttrust-sdk/trustgate/client";
+
+const facilitatorKey = Keypair.fromSecretKey(new Uint8Array(JSON.parse(process.env.FACILITATOR_KEY!)));
+
+const decision = await gatePayment({
+  rpcUrl:          "https://api.devnet.solana.com",
+  caller:          facilitatorKey,
+  payerAgentAsset: new PublicKey("5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y"),
+  payeeAgentAsset: new PublicKey("5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y"),
+  amount:          1_000_000n,                                                 // 1 USDC
+  mint:            new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
+  policyId:        1,
+});
+
+switch (decision.kind) {
+  case "Allow":
+    console.log("gate=Allow — proceed to settle");
+    break;
+  case "Deny":
+    console.log(`gate=Deny ${decision.reasonCode} (${decision.reasonName})`);
+    break;
+  case "RequireValidation":
+    const hex = Buffer.from(decision.capabilityHash).toString("hex");
+    console.log(`gate=RequireValidation capability=${hex}`);
+    break;
+}
+```
+
+## Implementation note — return-data channel
+
+PolicyVault's `gate_payment` (lazy variant) returns the decision via Anchor's `set_return_data` so simulation can decode it. The strict variant — used by [`composeAtomicSettleTx`](/sdk/exports-reference) — instead returns `Err` on non-`Allow`, which is what makes the atomic tx revert as a unit.
+
+`gatePayment()` simulates the lazy variant and parses the return-data via `parseGateDecision`. The wire format is documented in [`programs/policy-vault/src/state/decision.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/decision.rs).
+
+## Errors
+
+| Error | Cause |
+|---|---|
+| `AccountNotFound` | `PolicyAccount` PDA missing for `(payerAgentAsset, policyId)` — call `init_policy` first. |
+| `RPC error: insufficient funds` | `caller` keypair has zero SOL. Fund via `solana airdrop 1 <pubkey> --url devnet`. |
+| `IdlAccountUnsupported` | Program IDL not yet published on the cluster. Run `anchor idl init <programId> --provider.cluster <cluster>`. |
+
+For the atomic-settle path (which can also return `AtomicityNotEnforcedError`), see [`composeAtomicSettleTx`](/sdk/exports-reference).
+
+## Source
+
+- Client: [`trustgate/sdk/src/client.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/client.ts)
+- Simulation: [`trustgate/sdk/src/chain.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/chain.ts) (`simulateGatePayment`, `parseGateDecision`)
+- Types: [`trustgate/sdk/src/types.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/types.ts)
+- Tests: [`trustgate/sdk/test/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/sdk/test)