Pactwright-Kit

The TypeScript side of Pactwright: SDK, seller middleware, MCP tools and the verifier.
Everything an agent or a seller needs to use pacts, the escrow for AI-agent purchases on Stellar.

Documentation · Quick start · Evidence

[!IMPORTANT]
Testnet only, not published yet. Every MVP scenario runs as real Stellar testnet transactions
through the Kit's own code, including full x402 purchases through Accensa's hosted facilitator, and
a verdict from the hosted verifier has been accepted on-chain (evidence).
Nothing is on npm: .github/workflows/release.yml still has its
publish line commented out (ROADMAP K-17). The safest first read is
Testnet evidence, then
What "Supported" means here for what CI actually proves.

📖 Overview

A pact is an AI agent's purchase held in escrow on Stellar. The buyer locks a cap, a verifier checks
the delivery against a condition frozen before payment, and the seller is paid only what the verdict
allows. The rest returns to the buyer. The contract itself is in
Pactwright-contracts and runs on testnet.

AI agents can already pay over HTTP with x402:
the seller answers 402 Payment Required, the agent pays in USDC and retries. Once the money has
moved, though, the agent has no way to get it back if the delivery is wrong, partial or missing. The
pact contract fixes that on-chain. To use it, an agent, a seller and a verifier each need code that
speaks the same formats: they have to hash the condition the same way, sign the same bytes and agree
on what a delivery receipt is. This kit is that shared code, so neither side re-implements the
protocol and gets a byte wrong.

What runs today is the path money takes: hashing that matches the contract byte for byte, the
verifier's rules, receipt checks and signing, the contract client, and the seller's on-chain refund
and settle hooks. All seven MVP scenarios plus two full x402 purchases have run end to end on testnet
as 18 real transactions, linked below. The rest — the agent's account
sponsoring, the MCP tools and the CLI — is tested offline.

How it is checked: pnpm test measured 418 passed | 3 skipped (421 tests) across 45 test files on
2026-10-30, the vendored Witness and Accensa suites included, and Merkle proofs are tested against
Accensa's conformance vectors. A nightly workflow repeats the testnet run. The full documentation is
at pactwright.github.io/docs.

The kit builds on six projects rather than inventing their formats:

🏗️ Architecture

sequenceDiagram
    autonumber
    participant A as Agent<br/>(@pactwright/agent)
    participant S as Seller<br/>(@pactwright/seller)
    participant V as Verifier<br/>(services/verifier)
    participant P as pact contract<br/>(Pactwright-contracts)
    participant St as Studio<br/>(Pactwright-studio)
    A->>S: request
    S-->>A: 402 + pact terms (condition, verifier, deadlines)
    A->>P: open: lock the cap
    S-->>A: delivery + signed delivery receipt
    A->>V: POST /v1/verdicts with the evidence
    V->>P: record_verdict (signed attestation)
    S->>P: settle (rest returns to the agent)
    P-->>St: events
    St->St: index, batch receipts, anchor on-chain
    A->>St: fetch the certificate

In order:

1. The seller middleware answers 402 with the pact terms: the condition, the verifier's key and the deadlines.
2. The agent checks the terms, freezes the condition hash and opens the pact, which locks the cap in escrow.
3. The seller delivers and signs a receipt over the exact bytes delivered.
4. The verifier has a model read the delivery, applies deterministic rules, and signs a verdict envelope (Witness format) plus an on-chain attestation.
5. The contract pays the seller what the verdict allows and returns the rest.
6. Studio indexes the events and anchors a receipt, so the agent gets a certificate anyone can verify.

The components, and what each one actually does:

1. @pactwright/core — schemas, hashing, Merkle, amounts, network config.
   • Hashing (pactId, condition hash, signed messages) matches the contract; the testnet run checks the Kit's pact_id against the contract's on every open.
   • Amounts are decimal strings in TypeScript and i128 stroops on-chain, converted in only one place, amounts.ts, so a rounding bug cannot hide elsewhere.
   • loadNetworkConfig throws and lists every problem at once when the network configuration is incomplete.
2. @pactwright/contracts-client — typed client for the pact contract.
   • Generated from the contract's release bindings (scripts/fetch-bindings.sh, scripts/check-bindings.sh).
   • Used by the testnet run for open, record_verdict and release, and by the verifier's submit path through the facilitator's /pact/submit.
3. @pactwright/seller — the pact(options) middleware for x402 sellers, in Express and Hono forms.
   • Builds a valid x402 v2 402 with the pact terms, verifies and settles the payment through the facilitator before serving anything, derives pact_id from the verified payer, signs X-Pactwright-Delivery, and serves one pact once.
   • Refund and settle hooks: RefundVault.refund (M0, disputes) and settle (M2), sent as real transactions; the signing key comes from a KMS (KMS_KEY_ID) or, for development only, SELLER_SECRET_KEY.
   • No default payee, delivery key or verifier: it refuses to start rather than guess one.
4. @pactwright/agent — the buyer runtime: find, buy, await, certificate, plus metered sessions.
   • buy reads the 402, refuses terms that differ from the listing or the frozen condition, and pays with exact (M0) or pact (M2), signing only auth entries.
   • accounts.ts creates sponsored agent accounts (CAP-33 reserves plus a USDC trustline) and tops them up through RPC, and never returns the hash of an unsent transaction.
5. @pactwright/mcp and @pactwright/cli — the same runtime exposed to an LLM and to an operator.
   • MCP tools: find_sellers, buy, get_pact, dispute, get_certificate.
   • CLI commands: pactwright verify, pact, agent-create, agent-topup.
6. @pactwright/adapters — pluggable discovery, reputation, spending gate, wallet and verifier.
   • The Vespi gate and the Pollar wallet fail closed when their APIs are unreachable; neither has been exercised against the partner's real API (ROADMAP F-08 / F-09).
7. services/verifier — the Witness-compatible verifier service, and the trust boundary of the whole protocol.
   • A provider-neutral model adapter, deterministic rule functions, and a Hono HTTP service backed by a Postgres envelope store.
   • It holds no money and can only sign verdicts. The contract holds the funds, and a missing verdict falls back to the agreed silence policy, which by default refunds the buyer.

How the verifier decides. Its design follows one rule from
Witness: the model reads, code decides. A model is needed
because "is this a correct Portuguese translation?" cannot be checked by a hash — but the model only
reads, and the decision and the amount come from plain rules anyone can audit and re-run.

1. The model reads. An LLM turns the delivered document into a small structured reading, for example { detectedLanguage, pageCount, isTranslationOfSource, untranslatedSegments }. It never decides anything.
2. Code decides. A pure rule function turns that reading and the frozen condition into ALLOW or DENY, plus an amount. The same inputs always give the same verdict, so anyone can re-run the rules on the stored reading.
3. Everything is signed and kept. The verdict is a Witness verdict-v1 envelope. It records the criteria, reason codes, model ID and policy version, is signed with the verifier's key, and is retrievable by its hash. Envelopes live in Postgres, so their links keep resolving after a restart or redeploy.
4. If the model refuses, there is no verdict. The verifier doesn't guess. The pact falls back to its silence policy.

Example: document.translation. The condition is frozen before payment:

{ "kind": "document.translation", "lang": "pt", "minPages": 4, "maxUntranslatedSegments": 0 }

A failed mandatory criterion means DENY, and the buyer gets everything back. A short delivery is
paid pro rata: cap × pages ÷ minPages, rounded down. With a 1 USDC cap and 3 of 4 pages, the
seller is paid 0.75 USDC and 0.25 USDC returns to the buyer. code.review is the second condition
kind.

Status per piece.

Repository layout.

🧪 Test fixtures and the eval set

Four layers, each with a different claim to keep it honest.

• Unit and integration suite — pnpm test. Measured on 2026-10-30: 418 passed | 3 skipped
  (421 tests) across 45 test files, including the suites that ship with the vendored Witness core
  and Accensa SDK. The 3 skipped tests are the Postgres-backed envelope store; they run in CI, which
  starts a Postgres service and sets TEST_DATABASE_URL.
• Hashing conformance — packages/core/test/vectors. pactwright/
  holds this project's vectors (pact_id, condition_hash, delivery_receipt, receipt_leaf,
  usage_voucher, verdict_attestation, nonce, merkle), accensa/ holds Accensa's Merkle
  vectors. vectors.yml runs them on every pull request against the
  pinned contracts release, so a byte difference fails CI rather than the network.
• Rules eval — services/verifier/eval/cases/document-translation:
  52 labelled ALLOW/DENY cases, scored by pnpm eval on every push and pull request. It gates on
  ≥ 90%. Because it scores the rules against hand-written readings, it says nothing about the model.
• Real-model eval — services/verifier/eval/real: 29 labelled
  document.translation cases built from real documents (an English source, human translations in
  8 languages, unrelated texts), pushed through the full pipeline with the configured model. It costs
  money, so verifier-eval.yml runs it on demand and weekly,
  never per PR, and fails below 90%.
• Testnet end-to-end — e2e/testnet: every MVP scenario as real transactions,
  plus kms.e2e.ts and hosted-verifier.e2e.ts.
  e2e-testnet.yml runs it nightly and builds its job summary
  from the run's own report; nothing in the summary is hard-coded.

What these fixtures cannot see: the quality of a model reading outside the translation set, the real
Vespi and Pollar APIs (F-08 / F-09), pubnet behaviour, and anything about the contracts themselves,
which are tested in Pactwright-contracts.

📊 Testnet evidence

On 2026-10-29, every MVP scenario ran on Stellar testnet against the deployed
pact contract
with real testnet USDC
(CBIELTK6…DAMA)
and a fresh Accensa RefundVault
(CA77XYHJ…36SR),
deployed by the run itself. The Kit's own code did the work: core hashing, the verifier's rules and
signing, the contract client, and the seller's refund and settle hooks. The addresses above are the
ones recorded in the run's report; every run deploys its own vault, so they change each night.

The two x402 rows are the full purchase flow:

1. The Kit agent requests a resource from the Kit's pact() seller middleware and gets a 402.
2. The agent pays with its built-in x402 payment, signing only auth entries.
3. Accensa's x402 facilitator, hosted on testnet at https://pactwright-facilitator-testnet.onrender.com with the pact scheme, verifies the payment, pays the fee and settles it.
4. The seller serves the content with a delivery receipt, which is then checked like the verifier checks it.

For M2, the verdict and the seller's settle also go through the facilitator's /pact/submit.

What isn't real here: in this run the model's reading of each delivery is a fixture, so the verdict
depends only on the deterministic rules, and the non-x402 rows send their payments directly rather
than over x402. A run with a real model reading is the hosted verifier. The
full report, with buyer, seller and receipt leaves, is
e2e/testnet/results/2026-10-29.json.

Run it yourself. The nightly workflow runs it too, x402 rows included, against the hosted facilitator:

E2E_VERIFIER_SECRET=S… E2E_FACILITATOR_URL=https://pactwright-facilitator-testnet.onrender.com pnpm e2e:testnet

Seller key in a KMS. On the same date a RefundVault refund was signed through HashiCorp Vault
transit (ed25519, non-exportable), so the merchant key never left the KMS; the transaction's only
signature is the Vault key's. Report:
e2e/testnet/results/kms-2026-10-29.json, refund
fcb0d7a8…
at ledger 5451648. Reproduce with VAULT_ADDR=… VAULT_TOKEN=… KMS_KEY_ID=vault:… pnpm e2e:kms.

The hosted verifier

On 2026-10-29 the hosted verifier judged a real purchase with its real model (Google
gemini-3.5-flash-lite), and the contract accepted its signature. The script opened an escrow pact
with fresh accounts, committed the source and the delivered Portuguese translation to the public
evidence store, asked
pactwright-verifier-testnet.onrender.com for a verdict, then recorded it and settled. The script
never holds the verifier key, so the contract accepting the attestation shows the hosted service
signed it.

The pact in Studio: 40725564…5c55.
Report: e2e/testnet/results/hosted-verifier-2026-10-29.json.
Run it yourself (it needs write access to the evidence store) with
GITHUB_TOKEN=… pnpm e2e:hosted-verifier --reporter=verbose.

Hosted testnet services. All three are free-tier Render services, checked live on 2026-10-30.

[!NOTE]
Free tier: a cold start was measured at 42 s on the facilitator and 23 s on the verifier on
2026-10-30. The first call after the service sleeps is slow, not failing.

⚙️ Supported Versions & Compatibility

The pins below were read from the manifests in this repo: package.json,
.nvmrc, pnpm-workspace.yaml, packages/*/package.json,
services/verifier/package.json and the resolved versions in
pnpm-lock.yaml (lockfile version 9.0). The manifests are the source of truth for
intent; the lockfile only records a resolution.

What "Supported" means here

A row marked Supported means the pin is exercised by a CI gate on every push to main or every
pull request:

• ci.yml — pnpm lint, pnpm typecheck, pnpm test, pnpm build on
  Node from .nvmrc with a Postgres service for the envelope store, plus a verifier-image job that
  builds services/verifier/Dockerfile and asserts the container
  refuses to start when VERIFIER_SECRET_KEY and DATABASE_URL are missing.
• vectors.yml — core hashing against the pinned contracts vectors
  on every pull request.
• verifier-eval.yml — the rules eval per PR; the real-model
  eval on demand and weekly, failing below 90%.
• roadmap-check.yml — fails any PR that does not change
  ROADMAP.md.
• e2e-testnet.yml — the testnet run nightly, not per PR; it is
  a scheduled proof, not a merge gate.
• scorecard.yml — OpenSSF Scorecard weekly and on main.

Verified by hand rather than continuously: the testnet and KMS runs of 2026-10-29 recorded in
e2e/testnet/results, the hosted-verifier run of the same date, the real-model
eval of 2026-10-29 (run), and
the live checks of the three hosted services and the OpenSSF Scorecard on 2026-10-30, when this
repository scored 6.4/10 at main commit b39e236 (Pinned-Dependencies, Token-Permissions,
Security-Policy and Dangerous-Workflow all 10; Code-Review 0 because enforce_admins is off on
main, which no amount of code can fix).

Compatibility matrix

🚀 Quick Start

1. Installation

Requires Node.js 24 (.nvmrc) and pnpm 10.34.7 (packageManager in
package.json).

git clone https://github.com/Pactwright/Pactwright-Kit.git && cd Pactwright-Kit
nvm use                 # Node 24
pnpm install
pnpm typecheck          # also builds the vendored Witness core and Accensa SDK
pnpm build              # the publishable packages

To use the packages from another project before they are on npm, install them from the repo or link
the workspace packages; nothing is published to npm yet (K-17).

2. Configuration

Services refuse to start when configuration is missing or inconsistent, and they list every problem
at once. Copy .env.example and fill in what you run:

Every variable is explained in the
configuration reference, and the
testnet contract addresses are in
Pactwright-contracts/DEPLOYMENTS.md.

There are no defaults for anything that touches money: no default payee, delivery key, verifier or
model. The verifier's model provider is configurable, and the provider, model ID and reasoning effort
are recorded in every envelope, so a verdict can always be traced to what produced it — which is also
why the adapter fails closed instead of inventing a reading.

3. Usage

pnpm test               # 418 passed | 3 skipped (421 tests) across 45 files, measured 2026-10-30
pnpm lint
pnpm eval               # rules eval on the labelled document.translation cases
pnpm e2e:testnet        # every MVP scenario as real testnet transactions
pnpm e2e:kms            # a refund signed through a KMS (needs VAULT_ADDR, VAULT_TOKEN, KMS_KEY_ID)
pnpm e2e:hosted-verifier  # verdict from the hosted verifier, recorded and settled (needs GITHUB_TOKEN)

Core library.

import { toStroops, fromStroops, buildTree, verifyProof, loadNetworkConfig } from "@pactwright/core";

toStroops("1.25");        // 12500000n  (USDC has 7 decimals)
fromStroops(7500000n);    // "0.75"

const tree = buildTree([leafA, leafB, leafC]);          // 32-byte hex leaves
verifyProof(leafA, tree.proofs.get(leafA)!, tree.root); // true, same result as ReceiptAnchor.verify_receipt

const network = loadNetworkConfig(process.env);         // throws, listing every problem, if incomplete

Seller middleware. pact(options) for Express, pactHono(options) for Hono: one call turns an
x402 route into a pact-protected route. Runnable examples:
examples/seller-express,
examples/agent-node,
examples/metered-minutes.

Agent and MCP. @pactwright/agent exposes find → buy → await → certificate plus metered sessions;
@pactwright/mcp exposes the same as find_sellers, buy, get_pact, dispute,
get_certificate; @pactwright/cli exposes pactwright verify, pact, agent-create,
agent-topup.

Verifier HTTP API.

POST /v1/verdicts takes the pact terms, at least one evidence item, an optional seller
deliveryReceipt, and a milestone (delivery, or dispute-<n> for later disputes). The service's
own README is services/verifier/README.md, including the container
build and the Render deployment.

📊 Measurements

This README quotes as few numbers as it can. The figures are recorded in files, not in memory:
testnet transactions and contract and account addresses in the run reports under
e2e/testnet/results/ —
2026-10-29.json for the MVP scenarios,
kms-2026-10-29.json for the KMS-signed refund and
hosted-verifier-2026-10-29.json for the
hosted-verifier pact — real-model accuracy in the real-model job of
verifier-eval.yml (the run that produced 29/29 is
40897633766), and the
supply-chain score in the Scorecard results published by scorecard.yml.
Test counts, cold-start timings and the Scorecard reading quoted above were measured on 2026-10-30;
ROADMAP.md dates every one of them in its Update log.

🤝 Community & Maintainers

Join the discussion and get support:

• Discord: discord.gg/4WFU6fwPe
• Telegram: t.me/Pactwright
• Documentation hub: pactwright.github.io/docs
• Issues and pull requests: Pactwright-Kit issues
• Sibling repositories: Pactwright-contracts (MIT), Pactwright-studio (MIT)
• Vulnerabilities: report privately through SECURITY.md, never as a public issue

  Maintainer	Role	Scope
  @Pactwright/maintainers	Repository owners	Everything not listed below
  @Pactwright/core	Core team	packages/core/src/hashing.ts, packages/seller/src/delivery.ts, services/verifier/src/pipeline.ts, services/verifier/src/sign.ts, vendor/ — see .github/CODEOWNERS

The two handles are the teams named in .github/CODEOWNERS; requests to a
core-team path are reviewed by @Pactwright/core before they merge.

🛠️ Contributing

Read CONTRIBUTING.md, SECURITY.md and AGENTS.md first.
The rule that has no exception: every contribution updates ROADMAP.md — the status
of the tasks you touched, the progress counts, and one line in the Update log.
roadmap-check.yml fails any pull request that does not
change the file. main is protected, so a pull request needs one approving review and green checks.
Behaviour changes need an ADR in docs/adr/ before the code. Conventional commits, and
@Pactwright/core review for the paths above.

Setup is nvm use && pnpm install && pnpm typecheck && pnpm test;
CHANGELOG.md and the changesets in .changeset/ are how a release is
assembled once K-17 lands.

🧑‍💻 Contributors

License

Pactwright-Kit is released under the Apache License 2.0.

Copyright 2026 Pactwright contributors

What Apache-2.0 means for you

The no-warranty clause matters here because this code moves money and decides who gets paid. If you
run it, the risk is yours.

Why Apache-2.0 and not MIT

The kit includes Witness core in vendor/witness-core, which is licensed under
Apache-2.0. Keeping the whole kit under Apache-2.0 means a single set of terms covers everything in
the repo, and it adds an explicit patent grant. That matters for an SDK that other companies build
products on. The contracts and Studio repos contain no Apache-2.0 code, so they use MIT — which is
also why this repo is Apache-2.0 while Pactwright-contracts
is MIT.

Third-party code and licenses

Ideas used without copying code (Ficha, Vespi, BookerBob) and the Pollar integration (public SDK
only; Pollar Studio has no license, so none of its code is used) are credited in NOTICE.

Contributing under this license

Under section 5 of the license, anything you submit in a pull request is licensed under Apache-2.0,
the same as the rest of the repo. There is no separate contributor license agreement.