CAPPZ SDK. Build trusted agents.

Build document and agent workflows that retain their rules, history and ownership with the CAPPZ SDK.

Core value 6 of 7: Builds on existing standards — BPMN Engine and industry standards: ISO 20022, FIX, FpML, AL3/ACORD, HL7, EDI.

Build document and agent workflows that retain their rules, history and ownership. The reference SDK lets developers publish skills, BPMN flows and notarized content under their own HD root, with Replicator peer-path sync and optional integrations.

cappz.ai is the technical implementation of the Constitution of Trusted Agents (COTA). Every SDK primitive carries COTA provenance — identity, moral inheritance, zero-trust execution, no-harm bonds.

Notarized & lifecycle-managed

Sync by default

Constitution of Trusted Agents

Replicator

Replicator keeps every copy of a business document on the same version and records the history of each change.

Transporter

Transporter is how Replicator moves data: framed, encrypted, resumable, and proven on arrival by a checksum receipt.

CommandBridgeZ

CommandBridgeZ gives operators one bridge — Captain, Helm, Comms, Science and Engineering — over the same wallet context.

CAPPZ.AI Platform Capability Landscape

Others implement one or two layers. CAPPZ unifies embedded agents, a shared ontology, BPMN middleware, resident data with peer-to-peer sync, and build-to-release lifecycle in one wallet-native framework.

Where the work runs

26 functions run in your browser and 2 keep their records in the owning wallet. 70 still run hosted: 24 because they hold a third-party key (payments, AI, SMS, calendar OAuth, XRPL signing), ported last; 46 because their domain moves whole in the next release. 21 with no callers were retired.

26

In the browser

In the owning wallet

24

Hosted: hold a secret

46

Hosted: move next release

Whisper to find. Connect to move.

Discovery whispers on the LAN; across firewalls, copies ask. Peers find each other by UDP beacon, a TX bid/ask rendezvous with a relay node, pairing code or wallet breadcrumbs, then move the same checksummed frames over TCP, QUIC, a WebSocket bridge, an outbound relay ladder (WebTransport, WebSocket, HTTPS keep-alive, long-poll) or a USB bundle; nodes pull missing bodies by content hash. No inbound port behind a firewall, no browser required.

  • UDP beacon
  • TX bid/ask
  • Pairing code
  • Member table
  • Transport
  • Runs on
  • NAT
  • Offline
  • TCP
  • Standalone node
  • Needs a reachable port
  • LAN
  • QUIC
  • Standalone node
  • NAT-friendly (UDP)
  • LAN
  • WebSocket bridge
  • Browser → local node
  • Localhost only
  • Yes
  • Relay ladder (WebTransport · WebSocket · HTTPS)
  • Browser or node → relay node
  • Outbound only
  • No
  • USB bundle
  • Anywhere
  • n/a
  • Air-gap

A read-only XRPL connector watches validated ledger headers and checks anchoring proofs itself — no hosted verifier, and it never submits transactions.

Borrowed from Bitcoin: the peer pattern. Left behind: proof-of-work and global broadcast.

# standalone Replicator edge node (Deno) git clone https://github.com/CAPPZ-ai/cappz-sdk cappz && cd cappz && npm install # CAPPZ_NODE_KEY (PKCS8 base64) / CAPPZ_NODE_PUB (raw hex): Ed25519 key that signs hellos, beacons and TXs CAPPZ_POW=<your POW> CAPPZ_NODE_KEY=<pkcs8> CAPPZ_NODE_PUB=<hex> \ CAPPZ_TLS_CERT=cert.pem CAPPZ_TLS_KEY=key.pem \ deno run --allow-net --allow-read --allow-write --allow-env --unstable-net \ packages/cappz-edge-node/main.ts --tcp 41441 --quic 41443 --ws 41442 --relay 41445

Edge transports.

import { encodeJsonFrame, FrameDecoder, decodeJsonFrame } from '@cappz/sdk/transports'; const bytes = await encodeJsonFrame('inv', { heads: [headTxId] }); // CPZ1 · sha256 checksum const [frame] = await new FrameDecoder().feed(bytes); // survives any chunking const { heads } = decodeJsonFrame<{ heads: string[] }>(frame);
import { declareTransportCapabilities, mintPairingCode } from '@cappz/sdk'; // TransportCapabilityDeclared TX on your node's POW — latest wins, no registry. await declareTransportCapabilities(powAddress, ['tcp', 'quic', 'https'], ['udp-beacon', 'pairing-code', 'relay-rendezvous'], { tcp: 'tcp://10.0.0.5:41441', quic: 'quic://10.0.0.5:41443' }); const { code } = mintPairingCode(powAddress, publicKey); // speak it, type it, or show as QR
import { xrplPeerConnector, xrplWebSocketSource } from '@cappz/sdk'; const xrpl = xrplPeerConnector({ network: 'testnet', source: xrplWebSocketSource(XRPL_WSS_FROM_NETWORK_CONFIG) }); xrpl.start(); // watches validated ledger headers const ok = await xrpl.verify(anchorReceipt, receiptRoot); // read-only — never submits
import { openEdgeSession, generateSigningKey, signHello } from '@cappz/sdk/transports'; // Sign a fresh hello (Ed25519); the node verifies it and drops tampered or stale ones. const key = await generateSigningKey(); const hello = await signHello({ walletAddress, copyId, heads, transports: ['websocket'], discovery: ['pairing-code'], sentAt: new Date().toISOString() }, key); // Browser → local edge node over the WebSocket bridge (WebSocketStream: Chromium); the node carries TCP/QUIC. const ws = new WebSocketStream('ws://127.0.0.1:41442'); const { readable, writable } = await ws.opened; const peer = await openEdgeSession({ readable, writable, close: () => ws.close() }, hello); console.log(peer.helloCheck); // 'verified-unbound' | 'verified-bound' await peer.send('getdata', { ids: missingIds });

The 14 sections.

RepoZ — Federated Wallet Versioning

One cappz-repoz PTW defines the skill, policy, and BPMN. Its shared POW synchronizes public version heads. Each platform, app, and UAW branch includes that skill by reference while private bytes remain in the owning wallet.

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, baseVersionTxId });
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 is the User Application Wallet. Writes are default-deny and require a wallet-verified app Administrators grant scoped down from that app branch.

Clones vs Copies for Process Execution

A BPMN template declares its external and async IN/OUT ports once. Each running process instance is localized to the wallet instance that executes it; one wallet holds many process instances.

  • Clone (by value, owned): its own address root. Instances and instance ports are HD children of the clone, unique per clone. Clones are for wide distribution with active process execution on the edge.
  • Copy (by reference): tracks the template head as a connected shared library and owns no instance addresses, even when embedded in a clone (for example, the PTW copy inside the bible-codex POW and UAW clones). Its processes run in the host clone's instance scope.
  • Caution: every clone grows its own instance tree. Clone only where edge execution is needed. Instance ports are written only when a TX crosses them, and completed instances archive through replicate + purge.
const root = executingWalletRoot({ root: copyRoot, mode: 'copy', hostRoot: cloneRoot }); processInstanceAddress(root, 'BuildAgentCycle', 0); // <cloneRoot>/bpmn/BuildAgentCycle/instances/0'

1. Install & Bootstrap

The CAPPZ SDK is currently an in-repository module exposed through typed @cappz/sdk entry points; it is not an npm package. Skills, BPMN flows, and schemas hydrate from wallet-resident storage.

import { FetchSkillsOnChain } from '@cappz/sdk/skills'; const skills = await FetchSkillsOnChain(YOUR_HD_ROOT); // Skills resolve from the wallet-backed graph and hydrate the local cache.

2. Constitution of Trusted Agents (COTA)

cappz.ai is the technical implementation of COTA — the Constitution of Trusted Agents. Every SDK primitive maps to a COTA article: identity (Article I), moral provenance (Article II), zero-trust execution (Article III), no-harm bonds (Article IV), decentralized governance (Article V), radical transparency (Article VI).

Read the full charter at /cota. Every notarization, every event TX, every clone copy carries COTA provenance.

3. Replicator State Sync

Message sync is peer-path. Behind firewalls, copies dial out to a relay node an operator runs; it carries sealed frames it cannot read. Sign-in/admin may still be hosted. Sibling agent clones reconcile append-only block sequences through the same sync engine.

import { runSyncCycle, syncCacheWalletCopies } from '@cappz/sdk/sync'; const { peersFound, blocksApplied } = await runSyncCycle(walletAddress); await syncCacheWalletCopies(walletAddress, cacheWalletHdRoot);

The result: every clone converges on the same notarized graph state without a coordinator, replacing hub-and-spoke with viral blockchain sync.

4. Storage Stack (cappz-middleware)

All state flows through cappz-middleware. Raw browser storage APIs are prohibited (AX-63 — single storage stack).

cappz-middleware (OPFS device storage; legacy IDB rollback) ├── offlineCache (TTL KV) │ └── chainletStorage (high-level KV) ├── cappz-chainlet (block sync) ├── cappz-a2a (wallet-copy reconciliation) ├── cappz-sync-async (correlated envelopes) ├── cappz-mdm-cache (address-driven TX cache) └── cappz-model-adapter (AI inference) Event Bus: middlewareNotify(store, key, type) Subscription: CreateEventSubscription(hdPath, callback, eventType?)

5. HD Address Identity (AX-59)

Address-identity convergence: every entity's HD path IS its identity. All paths centralized inBibleCodexPaths.ts (AP-17 remediation — no hardcoded path strings).

m/44'/144'/0'/bible-codex/ ← BIBLE_CODEX_ROOT ├── ethiopian/{lang}/{book}/{ch}'/{v}' ├── kjv/{lang}/{book}/{ch}'/{v}' ├── peshitta/{lang}/{book}/{ch}'/{v}' ├── wlc/{lang}/{book}/{ch}'/{v}' └── nestle-1904/{lang}/{book}/{ch}'/{v}'

6. COOL & COPE Primitives

COOL (Cognitive Ontological Oriented Learning) — every dependency resolved through the on-chain ontology. No vocabulary drift, ever.

COPE (Cognitive Object Permanence Experiences) — eliminates constant re-inferencing. Learnings retained for consistent, reliable, and repeatable outcomes.

import { PrinciplesChainlet } from '@cappz/sdk/governance'; const verified = await PrinciplesChainlet.verifyPrincipleHash( principlePath, expectedContentHash, );

7. Generic Discovery — FetchSkillsOnChain (AX-68)

Generic HD-walk discovery utility. Replaces all domain-specific discovery functions.

import { FetchSkillsOnChain } from '@cappz/sdk/skills'; const configs = await FetchSkillsOnChain(YOUR_HD_ROOT); // → Discovers all bound skills under root // → Caches in chainletStorage (7-day TTL — AX-69) // → Reactive invalidation via CreateEventSubscription (AX-70)

8. CreateEventSubscription (AX-70)

Decentralized event subscription via cappz-middleware pub/sub. Zero third-party dependency leakage.

import { CreateEventSubscription } from '@cappz/sdk/sync'; const unsubscribe = CreateEventSubscription( 'cappz:codex/config/', // HD path prefix (key, value, mutationType) => RefreshCache(),// callback ['SkillBindingCreated', 'ContentAmended'], // event filter ); unsubscribe();

9. Royalty Flywheel

Every skill binding, every clone copy, every invocation emits a royalty event TX. Configs are inherited from wallet/skill scopes (AP-19 remediation — no per-TX royalty config).

// Mission gift split: 70 / 20 / 10 // 70% → skill author wallet // 20% → substrate treasury // 10% → COTA charter wallet // // 777 CAPPZ copy fee on every clone — distributed via flywheel.

10. Design Axioms

Wallet Sovereignty — local agent clones are self-governing

Sovereign Bootloader — skills loaded from wallet-resident storage

BPMN-First — all skill execution governed by a root BPMN process

HD Path Source-of-Truth — no hardcoded path strings

Single Storage Stack — all state through cappz-middleware

Generic On-Chain Discovery — FetchSkillsOnChain(hdRoot)

Config Cache — 7-day TTL on non-volatile datasets

Event-Driven Invalidation — CreateEventSubscription

Replicator wallet-copy reconciliation between sibling clones

DAG-Native Ingest — partition-scoped multi-parent nodes

Modal-Free Naming — no would/could/should/can/may identifiers

11. Anti-Patterns to Avoid

Resolution: Resolve from event TX existence

Resolution: Centralized constants/builders

Resolution: Wallet/skill scope inheritance

Resolution: Use action verbs (detectX, requestX)

12. Build Log & Upchain Synthesis

The SkillBuildLog records structural changes per clone. Entries sync upchain via A2A to parent templates — local learnings propagate to all siblings without breaking sovereignty.

Publish skills under your own HD root.

Royalty TXs to your wallets. Claude/MCP surfacing out of the box. Replicator peer-path sync between every clone.