@agenttrust-sdk/mcp 0.2.1 → 0.2.3

package/dist/embedded-docs/sdk/atomic-tx-invariant.mdx

@@ -0,0 +1,37 @@
+---
+title: Atomic-tx invariant
+description: SDK and facilitator rules that keep policy checks tied to settlement.
+---
+
+AgentTrust treats a policy check as useful only when the facilitator enforces the same payment context through settlement.
+
+Production settlement must compose:
+
+1. `gate_payment`
+2. SPL transfer
+3. `emit_feedback`
+
+All three succeed, or all three revert. That is the invariant that keeps a Pay.sh payment from settling without the AgentTrust feedback record, and keeps feedback from being emitted for a payment that never moved.
+
+## Adapter responsibilities
+
+The adapter validates that the retry proof still matches the verify-time context:
+
+| Check | Why it exists |
+| --- | --- |
+| `paymentIdHash` replay binding | prevents duplicate or raced settlement calls |
+| amount, mint, recipient cross-check | prevents paying a different asset or recipient than the policy checked |
+| facilitator fee payer != transfer authority | prevents self-pay feedback |
+| SERVICE-signed challenge | prevents forged `paymentRequirements` racing a legitimate one |
+| idempotent feedback lookup | makes retries return a stable receipt instead of double-emitting |
+
+## Demo vs production
+
+`examples/pay-sh-demo` stubs `validateOnChainTx` and `emitFeedbackCpi` so the route can run in CI. Production fills those same dependency seams with RPC parsing and the Anchor feedback call.
+
+| Source | Path |
+| --- | --- |
+| facilitator routes | [`trustgate/server/src/routes/settle.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/routes/settle.ts) |
+| Pay.sh proof validator | [`trustgate/server/src/facilitators/pay-sh/proof-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/proof-validator.ts) |
+| Pay.sh feedback helper | [`trustgate/server/src/facilitators/pay-sh/feedback.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/feedback.ts) |
+| Pay.sh demo deps | [`examples/pay-sh-demo/src/deps.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/pay-sh-demo/src/deps.ts) |

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

@@ -0,0 +1,22 @@
+---
+title: gatePayment
+description: Read-only policy decision call for facilitators.
+---
+
+`In progress`
+
+`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.
+
+For Pay.sh, the adapter path wraps this lower-level decision in:
+
+1. x402 challenge parsing
+2. SERVICE signature verification
+3. proof validation
+4. feedback emission
+
+| 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) |

package/dist/embedded-docs/sdk/index.mdx

@@ -0,0 +1,73 @@
+---
+title: "@agenttrust-sdk/trustgate"
+description: TypeScript client helpers, Express middleware, and atomicity guard.
+---
+
+The SDK is the facilitator-facing TypeScript package. The server adapter layer currently carries the concrete Pay.sh integration and the demo path; the package API remains the smaller client / Express surface for apps that call AgentTrust directly.
+
+```bash
+pnpm add @agenttrust-sdk/trustgate
+```
+
+## Imports
+
+```ts
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+import { gatePayment, settle, dispute } from "@agenttrust-sdk/trustgate/client";
+import {
+  AtomicityNotEnforcedError,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+  derivePolicyPda,
+} from "@agenttrust-sdk/trustgate";
+```
+
+## gatePayment
+
+`gatePayment()` is a read-only decision call.
+
+```ts
+type GateDecision =
+  | { kind: "Allow" }
+  | { kind: "Deny"; reasonCode: number; reasonName: string }
+  | { kind: "RequireValidation"; capabilityHash: number[] };
+```
+
+The helper simulates the Anchor instruction and parses the return-data channel into the TypeScript union.
+
+## mountTrustGate
+
+`mountTrustGate(app, config)` adds x402 routes to an Express service in fewer than 50 lines.
+
+```ts
+await mountTrustGate(app, {
+  rpcUrl: "https://api.devnet.solana.com",
+  facilitatorKeypair,
+  defaultPolicyId: 1,
+  network: "solana-devnet",
+  atomicityEnforced: true,
+});
+```
+
+## Atomicity guard
+
+`settle`, `dispute`, and middleware config require:
+
+```ts
+{ atomicityEnforced: true }
+```
+
+The marker is literal `true`, not `boolean`, and the runtime guard throws if a caller bypasses TypeScript with a cast. The server adapter path extends this into proof validation and feedback emission.
+
+## Current surface
+
+| API | Status |
+| --- | --- |
+| `gatePayment` | implemented |
+| `mountTrustGate` `/verify` | implemented |
+| `mountTrustGate` `/receipt` | implemented |
+| Pay.sh adapter | implemented in `@agenttrust/trustgate-server` workspace package |
+| Pay.sh demo | implemented in `examples/pay-sh-demo` |
+| `settle` | guarded SDK surface; server adapter validation path is active |
+| `dispute` | guarded SDK surface; negative feedback route remains narrower |
+
+Source: `trustgate/sdk/src`.

package/dist/embedded-docs/sdk/mount-trustgate.mdx

@@ -0,0 +1,15 @@
+---
+title: mountTrustGate
+description: Express middleware that mounts AgentTrust x402 routes.
+---
+
+`In progress`
+
+`mountTrustGate(app, config)` adds `/verify`, `/receipt`, `/settle`, and `/dispute` handlers to an Express service. The SDK enforces the atomicity config before binding routes.
+
+| Source | Path |
+| --- | --- |
+| Express middleware | [`trustgate/sdk/src/express.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/express.ts) |
+| x402 helpers | [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts) |
+| atomicity tests | [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) |
+

package/dist/embedded-examples/attestor-demo/README.md

@@ -0,0 +1,100 @@
+# attestor-demo
+
+Devnet ValidationRegistry attestor-lifecycle demo. Captures a real on-chain
+trace through all 5 ValidationRegistry instructions, proving the third leg
+of the ERC-8004 trust stack works end-to-end against the deployed devnet
+program at [`Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`](https://explorer.solana.com/address/Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv?cluster=devnet).
+
+```bash
+pnpm install
+pnpm --filter ./examples/attestor-demo run smoke
+```
+
+## Live devnet trace (2026-05-06)
+
+> **AgentTrust ValidationRegistry — full lifecycle, live on Solana devnet.**
+
+Subject (Quantu agent_account): [`5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y`](https://explorer.solana.com/address/5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y?cluster=devnet)
+Capability: `usdc-payment-policy.v1`
+
+| step | tx | PDA |
+|---|---|---|
+| **register_namespace** | [`5B3PfDGYhzhusJwj…`](https://explorer.solana.com/tx/5B3PfDGYhzhusJwjXURnhpkZ2umipdegfNREtJbcgZySR7nr976CcSJXqYSzB8eSYT14W3yrzGuks75S7pdZD3WK?cluster=devnet) | [`34gonn86FjxzXZMGd43RSvQVyH1r6PrGV9xnHXjjkEwR`](https://explorer.solana.com/address/34gonn86FjxzXZMGd43RSvQVyH1r6PrGV9xnHXjjkEwR?cluster=devnet) |
+| **register_attestor** | [`Ct3SQ4CR9bu6oijR…`](https://explorer.solana.com/tx/Ct3SQ4CR9bu6oijRELe7pnjj8KfMRVDiQ3AkytNQtYfF2yZBsThMJNoCDADnwWp37PYcsFJSEkBjXmaLY9a9eQD?cluster=devnet) | [`GTzWJzV5htNi1Ntqwq2e2ydu9h4rArnKQwzv2sJjC9zP`](https://explorer.solana.com/address/GTzWJzV5htNi1Ntqwq2e2ydu9h4rArnKQwzv2sJjC9zP?cluster=devnet) |
+| **request_validation** | [`qBQzSTCWfkE9Xw1E…`](https://explorer.solana.com/tx/qBQzSTCWfkE9Xw1EZ2qRwo3Hv451cbVaTRKSa32KHpnL7sfCSVBEhjGinm5qod6W6LtCgAj7xvbhydHf1wjoKq9?cluster=devnet) | [`GnbrSzWsDw1rehCrFJ4ckiM9JJJeAHdjfNDt7QQy7vhV`](https://explorer.solana.com/address/GnbrSzWsDw1rehCrFJ4ckiM9JJJeAHdjfNDt7QQy7vhV?cluster=devnet) |
+| **respond_to_validation** | [`CCxKvvQ9ZdboukcX…`](https://explorer.solana.com/tx/CCxKvvQ9ZdboukcXPp9jj1a3o53grGR9VjZux7kS1AAWqaVnRXVqhJjphsM1QYjny5oaVP4oRGThBLUQ41DyzwC?cluster=devnet) | [`C6Yr7oKcZ6sDVibR35SWbFnGCXyfQjLeRCiPbjxYq6vY`](https://explorer.solana.com/address/C6Yr7oKcZ6sDVibR35SWbFnGCXyfQjLeRCiPbjxYq6vY?cluster=devnet) |
+| **revoke_validation** | (gated on REVOKE=1) | (in-place — sets revoked=true on the attestation PDA above) |
+
+The `ValidationAttestation` PDA at row 4 is the on-chain artifact the
+PolicyVault's `RequireValidation` policy reads via the byte-offset
+parser at `programs/policy-vault/src/ext/validation_registry.rs`. Once
+this PDA exists for `(subject, capability, attestor) = (5PfaofvE…,
+sha256(usdc-payment-policy.v1), GTzWJzV5…)`, a subsequent
+`gate_payment` call that passes this attestation account through the
+`validation_attestation` slot turns a `RequireValidation` decision
+into `Allow`.
+
+Full machine-readable trace at [`devnet-attestor-trace.json`](./devnet-attestor-trace.json).
+
+## What this demonstrates
+
+1. **All 5 ValidationRegistry instructions reachable from the SDK**
+   (`@agenttrust-sdk/trustgate`'s `validation-registry` module exposes
+   PDA derivers + ix builders for every on-chain entry point).
+2. **The third leg of ERC-8004** is real on Solana — Quantu's
+   IdentityRegistry + ReputationRegistry sit at the foundation;
+   ValidationRegistry's capability attestation closes the trust stack.
+3. **The complete `RequireValidation` round-trip**: policy emits
+   capabilityHash → attestor responds → policy now Allows. Each step is
+   a separate on-chain tx; AgentTrust composes the PDAs without
+   trusting any off-chain coordination.
+
+## How it fits the demo narrative
+
+The Pay.sh adapter (in `trustgate/server/src/facilitators/pay-sh/`)
+already surfaces `capabilityHash` in its `formatChallenge` response when
+the policy gate returns `RequireValidation`. A SERVICE that hits this
+branch:
+
+1. Sees `decision.kind = "RequireValidation"` + `capabilityHash` in the
+   x402 `/verify` response body.
+2. Looks up the attestor service that handles that capability (typically
+   discovered out-of-band via a registry or hard-coded contract).
+3. Submits the claim payload off chain; the attestor responds on chain
+   via `respond_to_validation` (the script in this directory does this).
+4. Re-submits the payment to the SERVICE; the new `/verify` call
+   includes the `validation_attestation` PDA in the gate_payment
+   account list, the policy reads it, and the decision flips to
+   `Allow`.
+
+The script proves steps 3-4 work end-to-end on devnet. Steps 1-2 are
+business logic the SERVICE owns.
+
+## Configuration
+
+| env var | default | meaning |
+|--|--|--|
+| `RPC_URL` | `https://api.devnet.solana.com` | Solana RPC endpoint |
+| `KEYPAIR` | `~/.config/solana/id.json` | Facilitator keypair path |
+| `REVOKE` | (unset) | When `1`, runs the optional 5th step (revoke_validation) |
+
+## Cost
+
+~0.012 SOL across all 5 steps (rent for namespace + attestor +
+request + attestation PDAs, ~0.0023 SOL each, plus tx fees).
+
+## Idempotency
+
+Re-running reuses:
+- `examples/attestor-demo/attestor-keypair.json` (kept across runs so
+  the AttestorProfile PDA stays stable)
+- The namespace PDA (skipped if `fetchCapabilityNamespace` already
+  returns a record)
+
+It generates a fresh requester keypair each run so request_validation
+doesn't collide on the `(subject, capability, requester)` PDA.
+
+If you've already responded to a request once, the
+`(subject, capability, attestor)` PDA exists and respond is skipped —
+delete the attestor keypair file or change the `CAPABILITY_NAME` to
+walk a fresh attestation lifecycle.

package/dist/embedded-examples/pay-sh-demo/README.md

@@ -0,0 +1,136 @@
+# pay-sh-demo
+
+Pay.sh + AgentTrust TrustGate live-demo Express server. Single endpoint
+(`/protected`), gated by a counterparty-tier policy and exercised end-to-end
+through the AgentTrust facilitator pipeline.
+
+## Hit it now (no clone required)
+
+The demo runs **live** at `demo.agenttrust.tech`. Hit `/protected` with
+no payment proof and you'll get back a real x402 v2 challenge envelope:
+
+```bash
+curl -i https://demo.agenttrust.tech/protected
+```
+
+You'll see `HTTP/2 402` with a SERVICE-signed `payment-required` header
+(base64 envelope). To walk the full Allow → settle → emit_feedback path,
+clone the repo or use the `pay` CLI sandbox below.
+
+## Run locally
+
+```
+pay --sandbox curl http://localhost:3402/protected
+```
+
+## Live devnet trace (2026-05-06)
+
+> **AgentTrust + Pay.sh atomic settlement, live on Solana devnet.**
+
+| step | tx |
+|---|---|
+| signed SPL transfer | [`5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD`](https://explorer.solana.com/tx/5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD?cluster=devnet) |
+| emit_feedback CPI (PDA-signed → `agent_registry::give_feedback` → `atom_engine::update_stats`) | [`jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) |
+| FeedbackEmissionLog PDA (init-only, score=100) | [`HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) |
+
+Captured in [`devnet-smoke.json`](./devnet-smoke.json). Reproduce with `scripts/devnet-smoke.ts`.
+
+## What it shows
+
+The demo proves the full Pay.sh → AgentTrust loop without depending on a real
+Solana RPC connection:
+
+1. The CLI hits `/protected` with no payment.
+2. The middleware emits a `402 Payment Required` carrying the x402 v2
+   `PAYMENT-REQUIRED` envelope (base64). The envelope embeds AgentTrust's
+   policy hints in `extra.agentTrust`.
+3. Pay.sh signs the payment locally (Surfpool sandbox) and retries with
+   `PAYMENT-SIGNATURE`.
+4. The middleware:
+   - calls `PaySh.parseRequest` → `VerifyContext`
+   - calls `decide(ctx)` — the demo policy maps the `X-Demo-Payer-Agent`
+     header to a counterparty tier and compares against `minTier=2`
+   - on **Allow**: validates the proof shape, emits a synthetic feedback
+     CPI signature, and forwards to the resource handler
+   - on **Deny**: returns 402 with the reason code from the gate decision
+
+## Three demo counterparties
+
+The `defaultCounterpartyTable()` in `src/index.ts` seeds three deterministic
+agent PDAs:
+
+| header value (X-Demo-Payer-Agent) | tier | expected outcome |
+|--|--|--|
+| (output of `seed("tier0")`) | 0 | **402 Deny** — `CounterpartyTierBelowMin` |
+| (output of `seed("tier1")`) | 1 | **402 Deny** — `CounterpartyTierBelowMin` |
+| (output of `seed("tier3")`) | 3 | **200 Allow** |
+
+Hit `GET /health` for the actual base58 strings. Then drive each path with
+the matching header.
+
+## Run
+
+```bash
+# from repo root
+pnpm install
+pnpm --filter ./examples/pay-sh-demo build
+pnpm --filter ./examples/pay-sh-demo dev
+# server listens on :3402
+
+# in another shell — Allow path (tier 3)
+PAYER=$(curl -s http://localhost:3402/health | jq -r '.counterparties[2].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" http://localhost:3402/protected
+
+# Deny path (tier 0)
+PAYER=$(curl -s http://localhost:3402/health | jq -r '.counterparties[0].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" http://localhost:3402/protected
+```
+
+If the `pay` CLI isn't installed, the integration tests in `test/` exercise
+the same flow via supertest with synthesised x402 challenge / proof bodies.
+
+```bash
+pnpm --filter ./examples/pay-sh-demo test
+```
+
+## Configuration
+
+| env var | default | meaning |
+|--|--|--|
+| `PORT` | `3402` | HTTP port |
+| `NETWORK` | `solana-devnet` | network slug — must match Pay.sh's `--sandbox`/`--mainnet` flag |
+| `MINT` | USDC mainnet | SPL mint advertised in the `extra.asset` field |
+
+## Two modes: demo vs production
+
+The demo ships **two boot paths**:
+
+### `createDemoApp` (default `pnpm dev`)
+
+Synthesises chain interactions in-process — no Solana RPC needed,
+deterministic fixtures. Useful for CI smoke and local iteration. Three
+counterparty tiers are seeded from a static table; payment proofs are
+synthetic; `emit_feedback` returns deterministic signatures.
+
+### `createRealDemoApp` (used by `demo.agenttrust.tech` in production)
+
+Real Anchor `Program<TrustGate>` wired to live devnet. Real
+`validateOnChainTx` parses signed VersionedTransactions via RPC. Real
+`emitFeedbackCpi` lands `FeedbackEmissionLog` PDAs on chain. Real
+`simulateGatePayment` calls the deployed `policy_vault` program for every
+verify request.
+
+The hosted demo at `https://demo.agenttrust.tech` runs `createRealDemoApp`.
+Every `/protected` call traversing all three counterparty tiers writes a
+real on-chain artifact. The Phase C smoke trace
+([`devnet-smoke.json`](./devnet-smoke.json)) was captured from this exact
+boot path against devnet.
+
+## Adding to the demo
+
+- New counterparty tier: append to `defaultCounterpartyTable()` in
+  `src/index.ts`.
+- New gated route: import `paymentMiddleware` and mount it next to
+  `/protected`.
+- Real chain wiring: build a deps factory that returns the same `PayShDeps`
+  shape, replace `makeDemoPayShDeps()` in `createDemoApp`.

package/dist/embedded-examples/pay-sh-demo/src/deps-real.ts

@@ -0,0 +1,150 @@
+/**
+ * Production `PayShDeps` factory — wires real Anchor + RPC into the
+ * adapter. Companion to `deps.ts` (the in-memory mock) for the
+ * INTEGRATION=1 path.
+ *
+ * Real chain dependencies:
+ *   - validateOnChainTx → trustgate-sdk's makeValidateOnChainTx (parses
+ *     VersionedTransaction, polls connection.getSignatureStatus)
+ *   - emitFeedbackCpi   → trustgate-sdk's makeEmitFeedbackCpi (Anchor
+ *     methods builder, signed by facilitator keypair)
+ *   - priorEmissionLookup → trustgate-sdk's makePriorEmissionLookup
+ *     (fetches FeedbackEmissionLog PDA + recovers signature via
+ *     getSignaturesForAddress)
+ *
+ * Quantu account resolution: the demo expects `resolveQuantu(payeeAgent)`
+ * to return the bundle of Quantu accounts (asset, collection, optional
+ * ATOM) for the given payee agent. For the integration test we use a
+ * static map (the demo's payee Quantu accounts are pre-registered or
+ * mocked as cloned mainnet accounts under `anchor test`).
+ */
+
+import { AnchorProvider, Idl, Program, Wallet } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+
+import {
+  DEFAULT_DEVNET_QUANTU_IDS,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+  MAINNET_QUANTU_IDS,
+  QuantuFeedbackAccounts,
+  QuantuProgramIds,
+  deriveQuantuFeedbackAccounts,
+  loadTrustGate,
+  makeEmitFeedbackCpi,
+  makePriorEmissionLookup,
+  makeValidateOnChainTx,
+} from "@agenttrust-sdk/trustgate";
+
+import {
+  PayShDeps,
+  ReplayCache,
+  signEnvelope,
+} from "@agenttrust/trustgate-server";
+
+export interface MakeRealPayShDepsArgs {
+  /** RPC endpoint (e.g. https://api.devnet.solana.com). */
+  readonly rpcUrl:           string;
+  /** Network slug — gates the adapter against mismatched challenges. */
+  readonly signingNetwork:   string;
+  /** Facilitator keypair — payer for emit_feedback, signer of decisions. */
+  readonly facilitator:      Keypair;
+  /** Quantu account resolver. The integration test wires a static map. */
+  readonly resolveQuantu:    (payeeAgent: PublicKey) => Promise<QuantuFeedbackAccounts>;
+  /** Optional override of trustgate program ID (mainnet vs devnet). */
+  readonly trustgateProgramId?: PublicKey;
+  /** Optional Quantu program IDs override. Default = devnet (matches
+   *  programs/trustgate/src/constants.rs). Use MAINNET_QUANTU_IDS when
+   *  running under `anchor test` (clones mainnet pubkeys). */
+  readonly quantuPrograms?:  QuantuProgramIds;
+  /** Optional replay cache override (defaults to a fresh in-memory LRU). */
+  readonly replayCache?:     ReplayCache;
+  /** Optional locally-loaded Anchor IDL. When set, the demo skips the
+   *  on-chain IDL fetch (useful when the program is deployed but the IDL
+   *  hasn't been published via `anchor idl init`). */
+  readonly trustgateIdl?:    Idl;
+}
+
+export interface RealPayShDepsBundle {
+  readonly deps:        PayShDeps;
+  readonly connection:  Connection;
+  readonly trustgate:   Program;
+  readonly replayCache: ReplayCache;
+}
+
+/**
+ * Build a `PayShDeps` bundle backed by real Solana RPC + Anchor.
+ *
+ * Loads the trustgate IDL from chain (the program must be deployed at
+ * `trustgateProgramId` — defaults to devnet). Quantu account resolution is
+ * caller-supplied so the demo can plug in static fixtures or a real
+ * registry-walk strategy.
+ */
+export async function makeRealPayShDeps(
+  args: MakeRealPayShDepsArgs,
+): Promise<RealPayShDepsBundle> {
+  const trustgateId = args.trustgateProgramId ?? DEFAULT_DEVNET_PROGRAM_IDS.trustGate;
+
+  const connection = new Connection(args.rpcUrl, "confirmed");
+  const wallet     = new Wallet(args.facilitator);
+  const provider   = new AnchorProvider(connection, wallet, { commitment: "confirmed" });
+  const trustgate  = args.trustgateIdl
+    ? new Program(args.trustgateIdl, provider)
+    : await loadTrustGate(provider, trustgateId);
+
+  const validateOnChainTx = makeValidateOnChainTx({ connection });
+  const quantuPrograms    = args.quantuPrograms ?? DEFAULT_DEVNET_QUANTU_IDS;
+  const emitFeedbackCpi   = makeEmitFeedbackCpi({
+    trustgate,
+    trustgateId,
+    agentRegistryId: quantuPrograms.agentRegistry,
+    facilitator:     args.facilitator,
+    resolveQuantu:   args.resolveQuantu,
+  });
+  const priorEmissionLookup = makePriorEmissionLookup({
+    trustgate,
+    trustgateId,
+    connection,
+  });
+
+  const replayCache = args.replayCache ?? new ReplayCache();
+
+  const deps: PayShDeps = {
+    signingNetwork:    args.signingNetwork,
+    feePayer:          args.facilitator.publicKey,
+    validateOnChainTx,
+    emitFeedbackCpi,
+    priorEmissionLookup,
+    replayCache,
+    signDecision: (bytes: Uint8Array) =>
+      signEnvelope(bytes, args.facilitator.secretKey),
+  };
+
+  return { deps, connection, trustgate, replayCache };
+}
+
+/**
+ * Convenience: build a static Quantu resolver from a Map<payeeAgentB58, accounts>.
+ * Use this when the demo runs against a small fixed counterparty set.
+ */
+export function staticQuantuResolver(
+  table: ReadonlyMap<string, { asset: PublicKey; collection: PublicKey; atomEnabled?: boolean }>,
+  programs: QuantuProgramIds = DEFAULT_DEVNET_QUANTU_IDS,
+): (payeeAgent: PublicKey) => Promise<QuantuFeedbackAccounts> {
+  return async (payeeAgent) => {
+    const entry = table.get(payeeAgent.toBase58());
+    if (!entry) {
+      throw new Error(
+        `staticQuantuResolver: no entry for payeeAgent=${payeeAgent.toBase58()}. ` +
+        `Add it to the demo's Quantu account table.`,
+      );
+    }
+    return deriveQuantuFeedbackAccounts({
+      programs,
+      asset:       entry.asset,
+      collection:  entry.collection,
+      atomEnabled: entry.atomEnabled ?? false,
+    });
+  };
+}
+
+export { DEFAULT_DEVNET_QUANTU_IDS, MAINNET_QUANTU_IDS };