The public part of CAPPZ, version 15.49.1. Apache-2.0.
Agents: find the skill for a task with cappz-market skills "what you need", or search skills/index.json (every skill's when-to-use, commands and guide); llms.txt is the short map. People: start with the guide for what you are doing, below; the Constraint Guard walkthrough is animated (open it in a browser).
@cappz/sdk/port: move a PHP app off php-fpm one route at a time. Inventory the app, run each new handler beside PHP and compare every response, cut over on the evidence, roll back in about a second.@cappz/sdk/identity: KeyZ, wallet-keyed trust. Keys are trusted through declarations the wallet signs, with revocations replayed offline and short delegations; SD-JWT identity claims; X.509 as a projection of a declaration.@cappz/sdk/edge: KeyZ Gate, edge verification of signed HTTP requests (RFC 9421).@cappz/sdk/transports: copies that reach each other through firewalls and proxies: signed hellos, the HTTPS relay and tunnel, WebTransport and WebSocket rungs, LAN multicast, body pull, chunked bodies.@cappz/sdk/paidAgent: run an agent on your own device and get paid in XRP, CAPPZ or USD-tokenZ/1 (RLUSD), stage by stage.@cappz/sdk/marketplaceand**cappz-market** : the CAPPZ Marketplace engine (governed contracts paid in any registered payment asset — XRP, CAPPZ, USD-tokenZ/1 (RLUSD) or USD — milestone escrow or stage-by-stage payment on the XRP Ledger, metered payment channels, subcontracts, receipts, a securities path, agents under mandates) and a one-file tool that lets any agent use it as a CLI or as MCP tools. Agents start with the skillskills/using-cappz-marketplace ; all agent skills:skills/ . The CAPPZ counterparty check (packages/cappz-check-worker, a paid agent on a Cloudflare Worker) checks an address or party before you pay:cappz-market check; the same service evaluates a delivered stage against its agreed acceptance criteria (cappz-market evaluate), drafts listings from plain words (cappz-market draft) and scouts subcontractors (cappz-market scout). Before a large payment, thepayee confirmation (15.38.0,cappz-market confirm-payee) checks that payment instructions are the ones the payee declared on the market and endorsed from their own XRPL wallet, past a 72-hour cooling period — not merely an address that exists — and flags changed instructions and lookalike (poisoned) addresses; payees publish withcappz-market payee declare(an XRPL address, or a bank account by salted digest). Rules insrc/lib/marketplace/payeeConfirmation.ts; skillskills/confirming-payees . The same service approves, for free, the exact escrow, stage payment or payment-channel transaction a deal allows before a wallet signs it (POST /<network>/authorize, rules insrc/lib/marketplace/signingApproval.ts);cappz-market fund,release,redeemandclosesign nothing without it.@cappz/sdk/skills,/sync,/governance,/repoz: the wallet layer. Local-first storage (OPFScappz-store, memory elsewhere), the Replicator's sync primitives, hash-verified principles, and RepoZ versioning. A hosted mirror is optional: register one withregisterHostedClient, or run with none.@cappz/sdk/mesh: a resilience mesh for when the internet is down. Phones, laptops and small boards pass signed, delay-tolerant bundles device to device (hotspot, Wi-Fi Direct, WebRTC, BLE/LoRa fragments, USB sticks). KeyZ declarations and a KeyZ Gate check every bundle at every hop, offline. It includes text and voice messaging with names, messages to everyone, and blocking; LoRa via RNode boards; and native iPhone/Android shells.packages/cappz-mesh-noderuns it on Linux, macOS, Windows and Android, serves a browser app for iPhone, and builds a signed go-kit: a one-file program with Node.js runtimes that a device that was never set up can copy and run with no internet. Field guide:docs/MESH_FIELD_GUIDE.md .@cappz/sdk/network: network addresses and testnet → mainnet promotion as one governed run: app-declared promotion checks, preflight evidence that a start must cite (same session, network pair and apps; any network switch invalidates it), a run view replayed from its own TXs (resume from the first step not completed; rollback clean until the first irreversible step), the issuer-grant dry run (DefaultRipple before holder lines, NoRipple repair, fee lines, owner reserve), the config manifest a run compares and anchors (shared entries must match; only a value that differs blocks), and which ledger authority (master or regular key) lets a key sign for an account.docs/NETWORK_PROMOTION.md .@cappz/sdk/constraintsand theConstraint Guard (15.40.0): keep physical systems inside their safe envelope. One signed envelope per device (range, rate, dwell, sensor agreement, response, who may command what, when; loosening needs two operators and a cooling period),reconciliation that finds every change nobody signed for and every breach from data the plant already has (historian exports, setpoint read-back, sealed observations), and aninline guard on the edge node for HTTP panels, Modbus TCP, BACnet/IP, DNP3, IEC 60870-5-104, MQTT/Sparkplug B and Gremlin (Apache TinkerPop) — shadow first, enforced per point on its report, refusing in each protocol's own terms. Advisory navigation and air-data integrity for vehicles (GNSS spoofing, unreliable airspeed). Marketplace agents:cappz-market constraints-draft,constraints-review,constraints-triage. Guide:docs/CONSTRAINT_GUARD.md ; skillssecuring-control-systems ,monitoring-constraints .- Vault Guard (15.48.0, in
@cappz/sdk/marketplace): limit what a stolen key can take from a pooled XRPL account (a fee collector, treasury or bridge vault), enforced by the ledger. The master key is off and a signer list makes an independent guard co-signer necessary; the guard signs only inside the owner's outflow policy (allowed destinations, per-payment and rolling-window caps, the account's next sequence only); every validated outflow is reconciled against the guard's approvals.docs/VAULT_GUARD.md . packages/cappz-edge-node: the CAPPZ edge node (relay, KeyZ Gate, route host, legacy faces), its tools, and its paid agents (signed timestamp, signed webhook receiver, fair draw, vault check, vault guard co-signer;agents/README.md ).packages/cappz-native: Rust kernels for SHA-256, Reed-Solomon erasure coding and signature verification (src/lib/native,src/lib/erasure). NEON and the ARMv8 SHA-256 instructions natively, SIMD128 WebAssembly in browsers, TypeScript everywhere else. On a Snapdragon 8cx Gen 3: content addressing 8.5× faster, Reed-Solomon 10+4 at 1.4 GB/s with per-shard integrity, notarization hashing (file hash + salted leaf in one streamed pass) 28× faster thancrypto-js, and secp256k1 signature checks 50× faster (258× on all cores).docs/NATIVE_KERNELS.md .- Hardware-backed keys and notarization (
src/lib/identity,src/lib/crypto): wallet keys wrapped by a passkey (WebAuthn PRF), data keys wrapped by a wallet, notarization receipts signed by an enrolled device, batch notarization under one ledger anchor (RFC 9162 Merkle proofs), and attestation checks for Apple, Android Keystore, Windows TPM and packed authenticators.docs/HARDWARE_TRUST.md .
Tutorials: Move off PHP · Identity and trust · Replicate through firewalls · Earn with an agent
-
verify.mjsand the guide's in-browser verifier read vault reports ({report, decisions?, alerts?}). They check the report, the decisions hash, and every decision and alert signed by the same declared key. The first live testnet hire ofvault-checkreturned a valid report, but the verifier read it as a bare record and printed INVALID. Test added insrc/test/edge-node-agents.test.ts. -
creating-cappz-listings: check a test hire with the verifier the listing names, not only the hire's hash check.
The edge node sells the Vault Guard as two paid agents (packages/cappz-edge-node/agents/vault.ts , wired inagents/server.ts ; served docsvault-check.SKILL.md ,vault-guard.SKILL.md , guide cards,llms.txt , OpenAPI).
vault-check(1 XRP, on completion): a signed report on a pooled XRPL account. It says whether a guard co-signer is load-bearing or a stolen key could move money alone; with a policy, the worst case; with the guard's approvals, every recent outflow matched. Read from the ledger; no key held.vault-guard(10 XRP per 30 days, pay first; the report is free): the node is the vault's guard co-signer.- Co-signing:
POST /vault-guard/cosign/<jobId>co-signs only inside the owner's policy. Every decision is signed. Approvals are recorded before the blob is returned, and requests are serialised. - Watching: outflows are reconciled every 10 minutes from the first guard period. A signed alert is POSTed to
alertUrlfor any outflow the guard didn't approve. The period ends with a signed report. - Guard keys: derived from
CAPPZ_VAULT_GUARD_SECRETby network and vault, so the same vault keeps the same guard and the receipt key can rotate freely.
- Co-signing:
- Only the vault can start or change its guard. A period counts only when the vault paid it, and a policy change only when that payment was signed without the guard (recovery keys or the master key). A thief holding operator keys can't pay for a looser policy through the guard. Unauthorised jobs get 403.
- Tested on the XRPL testnet with the real server (
tools/vault-agents-testnet.ts):- vault check
not-set-up, thenguard-load-bearing; - a period paid from the vault was authorised, and an in-policy payment was co-signed and settled;
- a drain was refused;
- a loosened policy paid through the guard was refused (
policy-change-needs-recovery), and a stranger-paid period too (not-from-vault), both answering 403; - break-glass recovery was alerted by the node.
- vault check
- vault check
- Unit tests:
src/test/edge-node-vault.test.ts.
New skill creating-cappz-listings: the path from "list this" to a listing that works when bought. It covers:
- the service exists and is tested
- the seller account and network
- fields and pricing (recurring services as at most 30-day periods)
- a description for people and agents
- testnet, one hire, then mainnet with the person's OK
- a final
findcheck Linked from skills/README (start here),llms.txt, and the using, drafting, managing, selling and edge-node skills.
npm run market:build now writesskills/index.json before bundling the tool. Before, the tool shipped the previous skills index, so a new skill couldn't be found withcappz-market skills until a second build.
-
src/test/vault-guard.test.tsruns in the node environment (as the other XRPL-key tests do): under a host app's jsdom suite,Wallet.generate()failed noble-curves' byte check. No code change. -
Vault Guard: a stolen key cannot empty a pooled account (
src/lib/treasury/vaultGuard.ts, exported from@cappz/sdk/marketplace; guidedocs/VAULT_GUARD.md ).- Why: on 2026-11-21 an attacker drained Chainflip's Ethereum vault (about $4.86 million) with a valid signature from its threshold signing key, made outside the normal signing system (a 39-digit nonce where the counter stood near 315,000), and laundered it in under ten minutes. A vault that pays whatever one key signs is limited only by its balance.
- Setup (
guardSetupTransactions,checkSignerSetup): master key off; a signer list where every operator key together cannot reach quorum, the guard alone cannot, the guard plus k operators can, two offline recovery keys can, and one recovery key plus every operator cannot (operator 1, recovery n+1, quorum 2n+2, guard 2n+2−k). The check reads account_info and names every way a key could bypass the guard. - Policy (
evaluateOutflow,guardCosign): allowed destinations and tags, per-transaction and rolling-window caps per asset (exact token decimals), capped fee, short expiry, the account's next sequence only (no tickets, no counter jumps), no partial payments, paths or extra fields, never a key/signer/account change. Every reason is returned. - Reconciliation (
reconcileOutflows): every validated outflow must match a recorded approval by intent hash (API v2DeliverMaxhandled); a failed but validated transaction without approval is stillunapproved; the report is hashed. - Tested on the XRPL testnet (
tools/vault-guard-testnet.ts): master keytefMASTER_DISABLED; both operator keys draining, removing the guard, or setting a regular keytefBAD_QUORUM; the guard refused the drain (sequence-gap, destination-not-allowed, over-tx-cap, over-window-cap); a 15 XRP in-policy payment succeeded; 20 more XRP past the 30 XRP window was refused; two recovery keys moved 5 XRP and reconciliation reported itunapproved; the attacker address was never created. Unit tests:src/test/vault-guard.test.ts.
-
A fair draw the edge node sells: winners nobody can steer, not even the node, and anyone can recompute (
packages/cappz-edge-node/agents/draw.ts, thedrawagent inagents/server.ts).- What people use it for: giveaway and raffle winners, audit samples, members or reviewers chosen by lot, random group assignment, tie-breaks. 0.1 XRP per draw, paid once up front.
- How it works: the buyer sends the list, or only its SHA-256 and size if it is private, plus the number of winners and a draw time (up to 30 days ahead). After payment the node signs a
DrawCommittedrecord (the list's fingerprint, size, winners, draw time and the latest validated ledger). It goes on a public, hash-chained log (GET /agents/draw/log, one record per commitment, each naming the one before it). At the draw time the seed is the hash of the first validated XRP Ledger ledger closed at or after it; partial Fisher–Yates over a SHA-256 counter stream with rejection sampling picks distinct entries (rulecappz-draw/v1). The node signsDrawPerformed. - Why nobody can steer it: the list is locked (and paid for) before the seed ledger exists. The seed depends only on the ledger and the list, so committing the same list twice changes nothing. A different list is a new paid commitment, visible on the log.
- Checking it:
verify.mjschecks both signatures and the timing, reads the seed ledger and the one before it from public XRPL servers, and recomputes the winners (--entriesfor a private list,--hash-entries list.txtto fingerprint one). A buyer can ask for a public draw:/agents/draw/draws/<jobId>then serves a page that re-runs every check in the browser, reading the ledger over a public XRPL WebSocket. - No declaration file to copy: the agents find the payout account's on-ledger KeyZ declarations of the node key themselves, in that account's ledger history (
discoverLedgerAnchorsinagents/ledgerKeyz.ts;CAPPZ_KEYZ_ACCOUNT, default the payout address, onCAPPZ_KEYZ_NETWORK, default mainnet, so the testnet twin uses the same declaration; re-read hourly). A declaration approved in Xaman, first time or renewal, now reaches the node with nothing copied. Once the account has declared the key, signing s whenever no declaration is valid (expired or revoked), exactly as with a file.CAPPZ_KEYZ_DISCOVER=0turns it off; akey-declarations.jsonstill works. Tested on the XRPL testnet: declare from the payout wallet, the agents' card showsdeclaredBy, a paid receipt verifies by r-address, revoke, signing s. - Paid-agent kit: a completion stage may now be free (share 0) after upfront stages that carry the whole price (
isFreeCompletion): pay first, collect when ready, one payment.cappz-market hirehandles it as is. - The guide page has a "Run a fair draw" form, and the draw has its own
draw/SKILL.md, OpenAPI entries andllms.txtline. Tested end to end on the XRPL testnet withcappz-market hire; the public page was checked in Chrome. Tests:src/test/edge-node-draw.test.ts.
-
src/lib/sync/__tests__/kvSegments.test.ts: the scoped-flush tests drain their backend before they end. A queued write's timer from one test fired under a loaded suite (cappz's full run) and wrote into the next test's stand-in file system. No code change. -
A small durable save no longer fails because a large unrelated write did. On an iPhone, a page that cached megabytes (the Bible canon) left those rows queued; the next signed-in save flushed them too, Safari failed the large write with
UnknownError("unknown transient reason (e.g. out of memory)") and the save failed.offlineCache.set(..., { durable: true }),setMany(and sochainletStorage.setItemsand everyrequireDurableevent batch) now await only their own batch:KvBackend.flush({ store, keys })writes the queued batches holding those keys as one segment and leaves the rest queued. A batch that shares a key with them goes with them, so no batch is split.flushActiveKvEngine(scope?)takes the same scope.- Background flushes write segments of about 2 MB (
SEGMENT_TARGET_CHARS), never splitting a write batch. One store's failed write no longer stops the others; it is retried with back-off (1 s doubling to 1 min). - Compaction after a segment write runs as its own step; the save that triggered it is already on disk, and a failed compaction only leaves more segments to replay. A full
flush()still waits for it. opfsWriteFileretries a transientUnknownErroronce after 150 ms, then once through the sync-access worker (a separate heap). Other errors fail at once. A failed writable is aborted so the retry can open the file.- Tests:
src/lib/sync/__tests__/kvSegments.test.ts(scoped flush beside a failing store, no split batch, segment-sized background writes, transient retry).
-
The payout account can vouch for the paid agents' signer on the XRP Ledger, signed in Xaman, with no seed anywhere. - Before: a KeyZ declaration needed the account's family seed, typed into
declare-node-key.tson some machine.- Now, for people: run
packages/cappz-edge-node/agents/declare-node-key.ps1. A QR code opens; scan it in Xaman and approve. That signs oneAccountSetfrom the payout account which changes nothing on the account (fee about 0.00001 XRP) and whosecappz/keyzmemo names the node key and how long it lasts (at most 90 days). The script waits for the ledger, then writes an anchor intokey-declarations.json.-Revokewithdraws it the same way;-Check,-Network testnet,-Hashand-Jsonare there too. One-time setup: an app key from apps.xumm.dev inxaman.env, since Xaman shows sign requests only from a registered app. Without one, the transaction JSON is printed for any wallet. - For agents:
skills/running-edge-node-paid-agentscovers it step by step, with the JSON result and exit codes (0 done, 3 declined or expired in Xaman, 4 not seen in time, 1 error). - Checking it: records sign in
payload.signerDeclaration = "xrpl:<network>:<tx hash>". The agents (every 5 minutes) andverify.mjs <file> <r-address>read the declaration and the account's later revocations from public XRPL servers (agents/ledgerKeyz.ts;verify.mjsstays dependency-free). The ledger has already checked that the account authorized the transaction, so Ed25519 accounts, regular keys and multisign accounts work too. The agents stop signing once the declaration expires or is revoked. - Tested end to end on the XRPL testnet: declare, serve, verify by r-address, revoke, refuse. The Xaman path was tested against a stand-in for its API.
src/test/edge-node-ledger-keyz.test.tscovers the rules, andverify.mjsagainst a stand-in ledger.
- Now, for people: run
-
src/test/edge-node-agents.test.tsruns in the node environment (// @vitest-environment node, like the other SDK tests). cappz runs the SDK's tests under jsdom, wherexrpl'sWallet.fromSeedrejected Node buffers from another realm ("Uint8Array expected"). No code change. -
A wallet, not the website's certificate, vouches for the paid agents' signer (KeyZ).
- The problem: buyers learned the signing key from the HTTPS page. That page's public-CA certificate proves who controls a DNS name, so whoever took over the name (for example a hijacked dynamic-DNS account) could serve another key.
- New tool:
packages/cappz-edge-node/tools/declare-node-key.tshas a wallet sign a KeyZ declaration of the node key into the node'skey-declarations.json. The wallet is ideally the payout account; its seed is typed at a hidden prompt and never stored.--expect <r-address>guards against the wrong seed,--checkprints the state, and--revokesigns revocations. - Agents: with the declarations file set (
CAPPZ_NODE_KEY_DECLARATIONS, picked up byrun-agents.ps1), every record signs inpayload.signerDeclaration, and every result carries the declarations and revocations it needs. Agent cards showdeclaredBy.GET /agents/key-declarations.jsonserves the current evidence. - Fail closed: with the file set but no valid, unrevoked declaration of this key, the agents refuse to start or to sign. A revocation stops signing within a minute.
-
verify.mjschecks who vouches, offline and still with no dependencies. - It verifies the declaration's secp256k1 wallet signature (BigInt ECDSA, low-S, as@noble/secp256k1) and prints the wallet's XRPL address (RIPEMD-160 + base58check, asxrpl'sderiveAddress).node verify.mjs <file> <r-address>requires that wallet. A signed revocation in the file or in--evidence key-declarations.jsonfails the record.
-
It verifies the declaration's secp256k1 wallet signature (BigInt ECDSA, low-S, as
-
The public-CA certificate (Caddy/Let's Encrypt) stays, only for the browser-facing
https://front door. -
Found while building: xrpl 4.x's
Wallet.fromSeeddefaults to Ed25519 even for a secp256k1 seed, which derives a different account. The tool reads the algorithm from the seed (decodeSeed). -
The paid agents' Windows launcher lets them read their own data folder (
packages/cappz-edge-node/agents/run-agents.ps1). 15.43.0 granted--allow-readon the SDK only, so the agents wrote jobs and results they could not read back: a paid result came back empty, and a restart forgot every job (nothing was lost on disk). The server now stops on any read error other than a missing file, instead of taking it for "no jobs yet" (onlyMissinginagents/server.ts). -
Paid agents for the edge node (
packages/cappz-edge-node/agents). The node key's signatures become two agents on the marketplace, paid in XRP stage by stage on the paid-agent kit: asigned timestamp (a file's SHA-256 in, a receipt signed by the node key out; 0.05 XRP on completion, the file never leaves the buyer) and asigned webhook receiver (a URL for 30 days that signs every POST; 2 XRP, 30% deposit, 70% for the signed bundle of all records). Run one instance per network: testnet validates every flow with free test XRP before mainnet takes real XRP. Every record is signed withpayload.network, so a free testnet receipt never passes for a paid mainnet one. -
Docs for people and agents, served by each instance (
agents/docs.ts, templates inagents/docs/): a guide with try-it forms (hash a file in the browser, pay from any XRPL wallet, download and verify the receipt),llms.txt, aSKILL.mdper agent, OpenAPI 3.1, andverify.mjs, an offline verifier for receipts and bundles (Node 20+ or Deno, no dependencies). All are filled with the instance's live price, network, payout address and signer. Agent cards link them indocs; a browser opening an agent's URL lands on its try-it form. Windows launcher, example settings and Caddy routes inagents/README.md ; new skillrunning-edge-node-paid-agents . -
The edge node's jobs server binds
127.0.0.1everywhere (main.ts --jobs,timers.ts,serveJobs).main.tsused to bind every interface, so a node published for peers (for example--relaybehind a reverse proxy) also offeredGET /txs, its signed job history, to its whole network. Timer ticks need outbound HTTPS only.CAPPZ_JOBS_HOSTnames another address (0.0.0.0for peers or webhook senders on the network);jobsHostFromandDEFAULT_JOBS_HOSTinsrc/lib/functions/edgeJobs.ts. -
Timers-only edge node (
packages/cappz-edge-node/timers.ts). Runs just the BPMN timers: no peer, relay, gateway or directory listener, and no npm package (the node key is imported with WebCrypto insigningKey.ts). The jobs server binds127.0.0.1(CAPPZ_JOBS_HOSTchanges it); ticks need outbound HTTPS only.deno run --cached-only --no-config … timers.ts --jobs 41444. -
main.tsstarts only the services you name (--tcp,--quic,--ws,--relay,--verify,--legacy,--ftps,--ldap,--routes,--saml,--constraints,--jobs; none named = all, as before). Each service starts on its own: one that cannot bind its port is logged and the rest keep running; the node exits 1 only when all of them failed. A busy FTPS port no longer ends the node. -
COPE principle checked once per page (
bootstrapCopeSubstrate,PrinciplesChainlet.ts). RepoZ checked the governing principle before every artifact it saved, and each check re-read/soul.mduncached, hashed it and could race to adopt or amend it. Concurrent callers now share one check, reused for the life of the page; a check that fell back to the offline stub is retried after a minute, and the stub no longer amends a real adoption (it used to, offline).resetCopeSubstrateCheck()forgets the shared check. -
Constraint envelopes (
src/lib/constraints/envelope.ts,@cappz/sdk/constraints). The owner's signed statement of what a device may do, for any setpoint-controlled device — a freezer, an oven, a dosing pump, a breaker. Constraint kinds are registry accounts (cappz/config/constraint-kinds/<id>):range,rate,dwell,agreement,response,authority,schedule; units are UCUM-checked; mode-scoped limits refuse while the mode is unknown. A tightening is active at once; a loosening (each listed in plain words) needsminRelaxSignersoperators and a cooling period; forks and edits are refused. -
Signed and armed commands (
authority.ts): one point, one value, ≤ 15 min, a nonce, an operator key; KeyZ declarations and revocations for grants that name a wallet. Protocols without a signature field use commands armed at the guard, one write each. -
Reconciliation (
reconcile.ts,tools/constraint-reconcile.ts): every change needs a matching authorised command (orphan-change), every value stays in the envelope; disagreeing sensors name the outlier; changes without effect, silence and gaps are their own states.Sealed observations (seal.ts): signed, chained batches at the collector, so an edited historian shows assealed-broken. -
Constraint Guard (
guard.ts,gateways.ts, edge nodeCAPPZ_CONSTRAINTS_CONFIG): HTTP/REST, Modbus TCP, BACnet/IP, DNP3, IEC 60870-5-104 (sequence numbers kept consistent across a refusal), MQTT 3.1.1/5 with Sparkplug B, and Gremlin Server bytecode. Shadow first; per-point enforcement on an operator-signed record citing the shadow report hash; fail modes per point (hold-last-good/pass-and-alarm); writes are atomic; privileged operations need the operator's allowance by name.tools/constraint-wizard.ts(keygen, init, draft-graph, declare, endorse, revoke, status, command/arm, enforce, shadow, doctor) andtools/constraint-selftest.ts(every protocol over real sockets). -
Adapters (
adapters/): Modbus, BACnet, DNP3 (link CRCs), IEC 104, MQTT, Sparkplug B (bounded protobuf reader, alias births/deaths), OPC UA PubSub JSON, historian CSV/JSON (long and wide), Apache TinkerPop GraphSON (writes, observations, envelope drafts from explicit graph structure). -
Vehicles, advisory only (
vehicle.ts): separation and offset between position sources, implied speed and GNSS clock offset; redundant air data asagreement. -
Finding your way: an animated walkthrough (
docs/tutorials/constraint-guard.html) and diagram in the guide;constraint-wizardwith no step prints what is in place and the next step;cappz-market helpis grouped by task;cappz-market skills <words>andskills/index.jsonfind the right skill; each check-service agent, its agent card and the marketplace discovery document link the skill that says how to use it. -
Marketplace agents on the check service (
advisor.ts;/<net>/envelope,/review,/triage): the envelope drafter keeps a limit only when its quote is in the manual verbatim with every number; the shadow-report reviewer and incident triage are rules only; inputs are checked against theirreportHash; answers are signed.cappz-market constraints-draft | constraints-review | constraints-triage. -
Acceptance criteria (
src/lib/marketplace/acceptance.ts). A listing, request, bid or subcontract can state what a deliverable must meet as data: media type, size, JSON keys, word count, sections, phrases, or yes/no rubric questions. They are checked before publishing and frozen into the milestone's terms when the contract forms (MilestoneTerm.acceptance). Use--acceptanceonsell,ask,bidandsubcontract. -
Stage evaluator (
stageEvaluation.ts;cappz-market evaluate, 0.05 XRP; skillevaluating-cappz-deliverables ).- It checks that the delivered file is the seller's published evidence, then checks each criterion: by rule, or by a model whose "yes" counts only with a verbatim quote.
- It returns a signed pass / fail / needs-human verdict. The verdict says whether the criteria were agreed in the contract or supplied by the requester.
- The contract's named evaluator can accept citing the verdict (
accept --verdict,evaluate --accept;MilestoneAffirmed.basis). The buyer still pays. - The file is not stored.
-
Listing drafter (
listingDraft.ts;cappz-market draft, 0.02 XRP; skilldrafting-cappz-listings ). Plain words become a checkedselloraskcommand. Catalog fields are validated, and numbers the person did not write are dropped and asked for. -
Subcontract scout (
subcontractScout.ts;cappz-market scout, 0.05 XRP; skillscouting-cappz-subcontractors ). It proposes work packages within what is unreleased, each serving an open milestone, with candidates from market search and replayed reputation, and a readysubcontractcommand for each. -
All three run as paid agents on the check service (
packages/cappz-check-worker:/<network>/evaluate,/draft,/scout), each with its own card, price and pay-to address. The model is configured (MODEL, defaultclaude-haiku-5-5; key as a Worker secret). Without a key, the evaluator runs rule criteria only and the scout plans by rules. -
Payment assets and rails (
src/lib/marketplace/paymentAssets.ts). Each asset is an MDM account atcappz/config/payment-assets/<id>and each way it settles is a rail atcappz/config/payment-rails/<id>; ids are vendor-neutral. Assets: XRP, the CAPPZ token, USD-tokenZ/1 (RLUSD, the first member of the USD-tokenZ familyusd-tokenz) and USD. Every asset is an equal option: a listing, request or bid is priced in it, the contract keeps that asset, nothing is converted, and fees come from the same fee schedule keyed by asset. An asset is offered on a network only when its configuration validates there (RLUSD is not issued on devnet). -
Rails.
ledger-escrow(XRP, one escrow per stage leg, as before);ledger-staged(CAPPZ and RLUSD: each accepted stage is paid directly on the ledger, seller net plus fee legs;cappz-market releasepays it);ledger-channel(metered XRP use through a payment channel:sell --metered,fundopens the channel,claim,redeem,close);card(USD through the payment processor);by-reference. The ledger's TokenEscrow amendment is enabled, but RLUSD's issuer does not allow trust-line locking, so RLUSD is paid stage by stage;cappz-market check --currencyreportsasset-escrowableorasset-staged. -
Bring your own funded wallet (
walletFunding.ts; no purchase provider is linked or integrated):fundingNeed()says what an account needs for a payment (amount, reserves, a trust line first for tokens) and how to get it: the faucet on testnet and devnet, an exchange withdrawal on mainnet. -
Counterparty check per asset :
currencyandamountrequest fields, both trust lines, and the issuer's freeze, authorization and trust-line-locking flags. -
Signing approvals also cover token stage Payments (
pay), PaymentChannelCreate (channel) and PaymentChannelClaim (claim). -
Agent identity : a KeyZ request-signing key declared on the agent's profile (
agentKeys.ts); mandates that bind it (mandate --bind-key); RFC 9421 signed requests to/authorizeand to paid agents (agentRequestAuth.ts); SD-JWT principal credentials with sealed, nonce-bound disclosure (principalCredential.ts); a signed A2A agent card athttps://check.cappz.ai/.well-known/agent-card.json(agentCard.ts); signed reputation attestations atGET /<network>/reputation/<partyId>(reputationAttestation.ts).packages/cappz-market/server.jsonis the MCP Registry entry; the npm package it names is not published yet. -
Subcontracts and evaluators : a seller hands part of a contract to another party as a child contract (
cappz-market subcontract), and a buyer may name a third-party evaluator (--evaluator) who accepts milestones (accept). -
Mandates per asset : a mandate covers one asset, and daily totals are counted per asset.
Needs Deno 2 for the edge node and tools, Node 22 for the tests, and PHP only to run the example PHP app.
git clone https://github.com/CAPPZ-ai/cappz-sdk cappz && cd cappz
npm install
deno run -A packages/cappz-edge-node/tools/php-port.ts inventory --src packages/cappz-sdk/examples/php-app --out ./port
npx vitest run
Moving your own app: docs/MOVE_OFF_PHP.md. Identity, KeyZ and transports: docs/IDENTITY_TRUST_TRANSPORTS.md. Edge node: packages/cappz-edge-node/README.md.
- Skills —
FetchSkillsOnChain: read the notarized skill catalog from the wallet graph, not a static registry. - Sync —
CreateEventSubscription,runSyncCycle,syncCacheWalletCopies: the Replicator's sync primitives for wallet copies. - Governance —
PrinciplesChainlet,principlesChainlet,sha256Hex: hash-verified principle anchoring (COPE). - RepoZ — one inherited wallet-native versioning skill with generic
ContentCreated/ContentAmendedhistory, multi-parent signed merges, branch-scoped administration, and exact build dependency manifests. - Frames and sessions (
@cappz/sdk/transports) — CPZ1 frames (encodeJsonFrame,decodeJsonFrame,FrameDecoder), pairing codes (mintPairingCode,pairingCodeValid), edge sessions (openEdgeSession) and hello helpers (asEdgeTransport,canonicalHelloJson). - Through firewalls (
@cappz/sdk/transports, 15.3.0) — TX bid/ask rendezvous and an outbound HTTPS keep-alive carrier with long-poll fallback (connectThroughFirewall,openHttpsTunnel), the relay node handler (createHttpsRelay), proxy simulation for tests (proxiedFetch,PROXY_PROFILES), and Ed25519 hello/beacon signatures (generateSigningKey,signHello,verifyHello,signBeacon,verifyBeacon). Relays verify hellos and take the ticket fromAuthorization, never the URL. Guide:https://cappz.ai/tutorials/replicate-through-firewalls . Since 15.4.0: the carrier ladder tries WebTransport and WebSocket first (dialWebTransport,dialWebSocket,proxiedSocketDialerfor tests), wallets vouch for device keys withdeclareHelloKey/verifyHelloKeyDeclaration(no registry needed), and edge sessions pull bodies by content hash (runBodyExchange,memoryBodyStore). - Identity and trust (
@cappz/sdk/identity, 15.9.0 / 15.10.0) — keep identity in a wallet and reveal only what a verifier asks for: claims as salted SD-JWT digests + ciphertext (recordClaim,openClaim), WebAuthn bindings without biometric data (recordBiometricBinding), issuer attestations as SD-JWT VC with ES256K anddid:key(attestClaims), sealed nonce-bound disclosure (requestDisclosure,answerDisclosure,verifyDisclosure). Trust keys without a certificate authority (declareKey,revokeKeyDeclaration,delegateKey,evaluateKey) and project them into X.509 for mTLS / QUIC / WebTransport (issueSelfSignedCertificate,parseCertificate).runIdentityTrustDemo()runs every step, including the refusals, and reports pass/fail — the live tutorial runs the same call:https://cappz.ai/tutorials/identity-and-trust . - Edge and legacy (
@cappz/sdk/edge) — KeyZ Gate, a Fetch-API verify gateway for nginxauth_requestor proxy mode (createVerifyGateway; requests signed with RFC 9421 viasignRequest/requestSigner, content verdicts viasignContentHash), the DMZ quarantine with receipts (createLegacyGateway,intakeQuarantined), the FTPS server session (createFtpSession), the read-only LDAP directory (answerLdap,ldapClient) and the FTPS/SFTP pull plan (curlPlan). - Versus X.509, and retiring legacy checks (15.11.0) —
runTrustComparisonmeasures KeyZ declarations against a CA chain + CRL on your device (revocation timeline, CPU per check, cost per million with labelled assumptions,TRADEOFFSincluding where X.509 stays and whether policy or technology keeps it).createShadowComparisonruns the gateway beside a legacy verifier (e.g. a PHP route) and gates its retirement on evidence;packages/cappz-edge-node/tools/compare-verifiers.tsandtools/gateway.tsrun the comparison on your own instance. Examples:packages/cappz-sdk/examples/php/verify_route.php(the legacy check, with its verdict headers) andpackages/cappz-sdk/examples/php/after_retirement.php(the route behind nginx auth_request). - SAML: catch forged logins, then refuse them (15.37.0) —
reconcileSamlLogins(@cappz/sdk/identity) finds SaaS logins your identity provider never issued, from two read-only log exports (Okta System Log, Entra sign-ins, or any CSV/JSON by field mapping), with gaps reported as their own state;sealIssuedBatchmakes the issuance record tamper-evident.createSamlGuard(@cappz/sdk/edge) is a second, independent check in front of a SAML ACS you host: one assertion in one place, no DOCTYPE/comments/namespace rebinding, signatures referencing their own element, SHA-256+, operator-signed certificate pins, issuer / destination / recipient / audience / time / InResponseTo / replay — shadow first, enforce on its report.packages/cappz-edge-node/tools/saml-reconcile.tsandtools/saml-guard.ts;docs/SAML_GUARD.md . 15.37.0:multi-tenant — one guard for every customer of a SaaS, the tenant chosen by the login URL, pins signed per tenant, and a response naming another tenant refused ascross-tenant; theXML signature verified built in (exclusive C14N, RSA/ECDSA, pinned keys only; tested against signxml/lxml), so a broken SP check is covered; onboarding from IdP metadata (idpFromMetadata), the configuration doctor (lintSamlTenants), per-tenant shadow → enforce by operator-signed records, andtools/saml-wizard.ts(guided or step by step, monitoring timers included). Agent skills:securing-saml-sso ,monitoring-saml-logins . - Payee confirmation: stop payment-instruction fraud (15.38.0,
@cappz/sdk/marketplace) — a payee declares where it is paid (buildPayeeInstructions: XRPL address + tag, or a bank account as a salted digest that never publishes the number) on the market's public log, which only its own account can write, and endorses the declaration from its own XRPL wallet with a no-op AccountSet naming the declaration's hash (prepareEndorsement); new instructions wait a 72-hour cooling period, revocation is immediate.runPayeeConfirmationanswers, for a payer: declared by this payee and nobody else, endorsed, in force, not revoked, replaced or expired, not a change from where you paid them before, not a lookalike of an address in your history — plus every counterparty-check fact — as a signed ok / warn / stop report (signPayeeReport). Paid agents may now pay each stage to its own address (PaymentStage.payTo): the service charges a platform fee up front to the CAPPZ treasury and its service fee to the operator. Skill:confirming-payees . - Shared admin-governed logs: bindings follow the account, not the browser (15.39.0,
@cappz/sdk/sync) — aCappzEventCacheopened with{ shared: true }keeps a public copy of governed writes in one partition of the hosted mirror per log (pub:<event-log address>): writes publish there first and reach the wallet only after the mirror accepted them; every device merges the copy on refresh and keeps it for offline use. Agent window bindings and skill compositions (agentSkillCache.persistBatch(entries, { share: true })) and shared app ledgers (createAppLedger({ shared: true })) use it, andshareExisting()backfills an admin's earlier records. The app registers the port (registerSharedEventLog(mirrorSharedEventLog(mirror, authorOf))) and owns the insert rule; unregistered, caches run local-only.sharedStatesayssynced,unreachable(device copy shown) orlocal-only. - Move off PHP, route by route (
@cappz/sdk/port, 15.12.0) —inventoryPhpAppreads a PHP app (routes, tables and file stores with their readers and writers, sessions, uploads, cron, secrets, libraries) and orders it in waves;createRouteHostserves ported routes, forwards the rest to PHP and shadows written ports (createRouteShadow,compareResponseswith explicit rules); cut-over and rollback are signed TXs (replayRouteModes);nginxLocationssends only ported routes through the host. Examples:packages/cappz-sdk/examples/php-app/(a small PHP orders API) andpackages/cappz-sdk/examples/port/routes.ts(its port). Tutorial:https://cappz.ai/tutorials/move-off-php - More transports (
@cappz/sdk/transports, 15.9.0 / 15.10.0) — one transport namespace (resolveTransportType), wallet multicast groups and signed UDP kick-off (walletMulticastGroup,buildConnectRequest,buildConnectOffer), files above 6 MB as chunks + manifest (putBody,readBody), and a processing farm: rendezvous partitioning (flowOwner,assignFlows) and reliable multicast with NACK repair and explicit loss (createFeedSender,createFeedReceiver). - Examples (
packages/cappz-sdk/examples/) —identity-flow.ts(TypeScript),sign_request.py(Python, RFC 9421 signing),cappz_drop.php(PHP, same spec, not run in CI),legacy-clients.sh(curl drops, FTPS, ldapsearch),nginx-cappz.conf. The TypeScript and Python examples run in this repository's tests as shipped. - Resilience mesh (
@cappz/sdk/mesh, 15.13.0): offline store-carry-forward between devices.- Founding a mesh. An authority wallet signs a charter (
createCharter; the mesh id is its hash) and grants roles (grantMembership,revokeMembership). Precedence runs FLASH / IMMEDIATE / PRIORITY / ROUTINE and is bounded by role. Guests are carried at ROUTINE. - Bundles. Each bundle is signed by a device key that the sender's wallet declared (KeyZ), carries its own credentials (sent by reference to neighbours that already hold them), and has its body sealed to the recipient's declared P-256 key (
sealBytesTo). - The gate.
MeshGateis a KeyZ Gate for bundles, applied at every hop: signature, body hash, key trust and revocation, membership, precedence, and per-source origination rate. - The node.
MeshNodeannounces then pulls over CPZ1 frames and routes with spray-and-wait plus PRoPHET. Receipts are signed by the recipient and verifiable by every carrier. The store has per-source quotas, and KeyZ revocations are gossiped at FLASH. - Links. - TCP on any local network.
- WebSocket for browsers.
- WebRTC with offline pairing codes (
offerPairing/answerPairing). - LoRa through
RadioMedium(a shared channel turned into links per neighbour, with an airtime budget and the duty-cycle rules inLORA_REGIONS) and KISS / RNode framing (kissEncode,rnodeConfigFrames). - Native radios through
attachNativeBridge: MultipeerConnectivity and Nearby Connections shells inpackages/cappz-mesh-native, not yet compiled. - Carry files (
writeCarryFile/readCarryFile).
- Messaging. Text and voice messages (
splitVoice,VoiceAssembler,recordVoice); signed, display-only names with nicknames and ambiguity-safe lookup (ContactBook); a channel for everyone (EVERYONE_CHANNEL); and a personal block list that stops showing and carrying a sender's messages while their revocations still apply. - Simulator and evals.
runSimulationandrunMeshEvals: dense, sparse, shelters with couriers, forgers, flooders, a captured device, black holes, forged receipts, and jammed BLE, each with declared thresholds. Run them withnpm run mesh -- evals [--full]. - Docs.docs/MESH_RESILIENCE.md covers the design;docs/MESH_FIELD_GUIDE.md is the field guide.
- Founding a mesh. An authority wallet signs a charter (
- Paid agents —
createPaidAgent,SCHEDULE_PRESETS,paymentRequest,checkPayment,replayJob: run an agent on your own device and get paid in XRP, CAPPZ or USD-tokenZ/1 (RLUSD) stage by stage (upfront deposit, milestones, completion). Payments count only when the validated ledger shows them delivered to your address with the stage's destination tag (and, for a token, from its registered issuer); each result is held (HTTP 402 in the ready-made agent) until its stage is paid. Guided setup:https://cappz.ai/tutorials/earn-with-your-agent . - Usage billing and the subscription agent (also
@cappz/sdk/paidAgent) — for marketplace apps, services and agents billed by use.- Plans (
AppUsagePlan,quoteUsage): pay as you go, subscription, subscription with overage, or sponsored (the app's treasury funds its users' app wallets). Prices in USD, XRP or both; conversion only with a fresh rate, never a guessed one. - Default prices are proposals (
proposeDefaultPrices): marked as not validated by the app owner and never charged until the owner acknowledges or changes them (applyOwnerDecisions). - Top-up rules (
FundingRule,decideFunding): low balance or short runway → propose a one-click or typed-command top-up, or top up automatically. Auto top-up needs caps (overall, per month, week, day, hour;capRoom); a rule with none only proposes. - Splits from the contract (
splitCharge,postingsFor): platform, app owner (ebb tenant) and talent shares in basis points, null or 0 allowed; unallocated shares need a named remainder party. Exact rounding; each line is an AP/AR pair. - Short on money (
planWithinBudget): critical tasks first, the rest deferred with exact shortfalls.estimateRunwayandprojectedVsActualreport spend. - The agent (
createSubscriptionAgent): storage, payment, notices and rates are ports; it holds no key.subscriptionWatchJobruns it on an edge node for sponsored top-ups from the app owner's treasury. - Platform adapter templates (
PLATFORM_ADAPTER_TEMPLATES,endpointOrder,withFailover): prioritised, weighted endpoints per service with back-off, and no hosting provider assumed. - Guide.docs/USAGE_BILLING.md .
- Plans (
Data lives in wallets, stored on the device first: OPFS (cappz-store) in browsers, memory in Node and Deno
tests. A hosted table mirror and hosted functions are a port, not a dependency
(src/lib/sync/hostedBackend.ts):
import { registerHostedClient } from '@cappz/sdk/sync';
registerHostedClient('routed', supabaseLikeClient); // optional: from(table) builders + functions.invoke
With nothing registered, reads return no hosted rows, writes stay local (the sync adapter queues them in its
outbox) and suggestMerge (a hosted agent) reports that it needs a backend. cappz.ai registers its own client.
import { includeRepoZSkill, createRepoZContent, amendRepoZContent } from '@cappz/sdk/repoz';
await includeRepoZSkill(appRoot);
await createRepoZContent({ appRoot, artifactId, objectType: 'document', contentHash, contentAddress, actorAddress, signature });
await amendRepoZContent({ appRoot, artifactId, objectType: 'document', contentHash: nextHash, contentAddress, actorAddress, signature, baseHeads });
The shared RepoZ POW is read-only by default. Each app's Administrators group may receive a wallet-signed amendment grant scoped from that app branch top node downward. Private bytes remain in the owning wallet; shared branches carry only version identity, hashes, dependencies, and build evidence. Grant issuance is deliberately absent from this public SDK until the trusted group-replay signer boundary is connected.
Each current location of documents have a repoz skill. If the included skill is anchored on a branch of the chain based graph, there is both functional isolation coordinated shared versioned reuse in a distributed manner.
Create a single cappz-repoz wallet PTW that includes RepoZ skill. Because each App and platform PTW holds the RepoZ skill respectively anchored to their sub graph of the ontological blockchain platform graph, any overlapping branches are multi-master version coordinated. Each app builds of specific versions. App dependencies are traced via Txs within each App PTW. The vin diagram dependency graph made manifest. Each App PTW, PTO, and UAW have the embedded auto-syncing cappz-repoz seeparate from their private namespace encapsulating wallet whereee instance specific private content is strored.
from the app specific branch top node down. Same scoping as the resident admin agent. Distributed synchronized and tenant ring-fenced federated development repoz. Need BPMN to capture it all.
PTW means Prime Template Wallet. PTO/POW is the Prime Operational Wallet.
UAW means User Application Wallet. See the full BPMN and architecture guide
in docs/CAPPZ_REPOZ_GUIDE.md.
Archive = Replication + purge. Three notarized TXs: ContentCompressed (source → <address>/compressed/gzip child alias), ContentArchived (source → archive wallet, from a verified one-way Replicator receipt), ContentPurged (AgentAdmin → original, last; placeholder never replicates). See docs/CAPPZ_REPOZ_GUIDE.md.
Lazy decompress (decompress only on a cache hit): the index and metadata load on boot; code and documents stay gzip-compressed in memory and are unzipped, hash-checked, only when opened (lazyContent), then kept in the hot cache. Untouched content costs no memory or CPU.
Archive activation (v14-16-04): the Archive button checks every platform/app wallet for an archive replica; missing ones are created with ReplicantCreated + derived ArchiveCreated (same correlationId), then archive-content.bpmn runs. Only deltas are archived: content with no ContentArchived TX.
BPMN templates declare external/async IN and OUT ports once. A running instance is localized to the executing wallet: processInstanceAddress(walletRoot, process, n).
- Clone (by value): own root; instances and instance ports are unique HD children of the clone. Use for wide distribution with active edge execution.
- Copy (by reference): a connected shared library tracking the template head; owns no instance addresses, even when embedded in a clone (e.g. the PTW copy inside bible-codex POW/UAW clones). It runs in the host clone's scope (
executingWalletRoot). - Caution: each clone grows its own instance tree. Instance ports are written only when a TX crosses them.
Process → function bindings are written by ConstructBPMN → BindBPMNFunctionsOnchain (idempotent diff of ConstituentIncluded/ ConstituentRemoved), from the build cycle or on demand by an admin.
git clone https://github.com/CAPPZ-ai/cappz-sdk cappz && cd cappz && npm install
Not on npm yet: use it from a clone (or as a git submodule).
import { encodeJsonFrame, FrameDecoder, mintPairingCode } from '@cappz/sdk/transports';
const frame = await encodeJsonFrame('ping', { at: Date.now() });
Identity in five lines, and the whole flow checked in one call:
import { runIdentityTrustDemo } from '@cappz/sdk/identity';
const report = await runIdentityTrustDemo();
console.log(report.passed, 'of', report.steps.length, 'checks passed');
Verify requests at your reverse proxy (any Fetch runtime: Deno, Bun, Node 18+, workers):
import { createVerifyGateway } from '@cappz/sdk/edge';
const gateway = createVerifyGateway({ evidence: { evidenceFor: async (wallet) => loadDeclarations(wallet) }, requireBound: true });
Deno.serve({ port: 41446, hostname: '127.0.0.1' }, (req) => gateway.handle(req)); // nginx auth_request → /cappz/verify
On one x86-64 machine (not ARM), against the example apps:
| PHP | CAPPZ | |
|---|---|---|
| 300 overlapping orders (php-fpm, 32 workers) | confirmed 88, kept 12, 212 failed | kept 300 of 300 |
| Throughput, orders API | 34,662 req/s | 45,593 req/s |
| Requests signed with revoked keys | 360 of 360 accepted | all refused |
| Replayed requests | 359 of 359 accepted | all refused |
Rerun on yours: packages/cappz-edge-node/tools/write-race.ts, bench-routes.ts, compare-verifiers.ts.
packages/cappz-sdk/*.ts are the entry points; src/ holds the library code they use; packages/cappz-edge-node is the edge node and its tools; docs/ the guides. Paths are the ones the tutorials use.
This repository is the only source of this code. The CAPPZ platform uses it as a git submodule, so a change lands here first. Issues and pull requests are welcome. Run npx vitest run and npx tsc --noEmit before a pull request.