Programmatic Transactions Build Series

Five TypeScript packages for moving value, attesting facts, and gating access on the Demos network — from code, without manual steps.

Built by Kynesys Labs on @kynesyslabs/demosdk@^4.0.14.

---

The builds

#	Package	What it does
1	@kynesyslabs/agent-allowance	Spending policy engine for autonomous agents. Every transaction is evaluated against hard, locally enforced caps before any OS leaves the wallet.
2	@kynesyslabs/dahr-verify-bot	URL attestation. A Demos node fetches a URL and commits the response hash on-chain. Returns the transaction reference and an attestation card.
3	@kynesyslabs/pow-receipts	Verifiable work receipts. Client escrows, contributor proves GitHub identity, escrow releases. Three on-chain transactions rendered into a publicly verifiable receipt URL.
4	@kynesyslabs/fair-launch-gate	Identity eligibility gate. Chains GitHub attestation, Human Passport, and Nomis wallet reputation into a single check with a transparent decision trace and an embeddable badge.
5	@kynesyslabs/d402-demo	Agent-governed pay-per-call. An autonomous agent pays per API request over the d402 rail. Build 1's policy engine governs every purchase before settlement.

---

How the builds relate

@kynesyslabs/agent-allowance  (Build 1)
│
│  The spending policy engine. Shared by Build 5 at runtime.
│  The decision trace format, result envelope, ledger adapters,
│  and MCP patterns are reused as a convention across all builds.
│
├── @kynesyslabs/dahr-verify-bot  (Build 2)
│   Standalone. Uses demos.run.attest.dahr — no Build 1 dep.
│
├── @kynesyslabs/pow-receipts  (Build 3)
│   Standalone. Uses demos.run.escrow.* + demos.run.attest.github.
│
├── @kynesyslabs/fair-launch-gate  (Build 4)
│   Standalone. Reads Identities.* — no wallet required for checks.
│
└── @kynesyslabs/d402-demo  (Build 5)
    Depends on Build 1. Build 1's PolicyEngine governs every d402
    purchase; the d402 rail executes the settlement.

Future: Build 5 is designed to govern Builds 2–4's on-chain calls under Agent Allowance policy — the dependency graph will complete once Build 5 is fully wired.

---

Common prerequisites

All five builds share these requirements:

• Node 20+, TypeScript strict, ESM, pnpm
• @kynesyslabs/demosdk@^4.0.14 — earlier versions have auth issues; 6.0.1 is a stale 2025 build
• ESM patch — the 4.0.14 build ships extension-less imports that break native Node ESM; each repo carries patches/@kynesyslabs__demosdk.patch and applies it via pnpm patch
• DEMOS_RPC_URL=https://node2.demos.sh — the only allowlisted testnet RPC; non-allowlisted hosts are refused at construction
• DEMOS_AGENT_MNEMONIC — twelve-word mnemonic loaded from env; never logged, never committed
• Testnet DEM — fund wallets via POST https://faucetbackend.demos.sh/api/request with body {"address":"0x..."} (2400 DEM per request)

---

Shared design patterns

Every build in the series follows the same discipline:

Fail closed. Any ambiguous state, RPC error, or policy miss refuses rather than proceeds.

Decision trace. Every policy evaluation returns a full decisionTrace — every rule evaluated (no short-circuit) with its pass/fail and observed values. The trace is the demo asset.

Uniform result envelope. { ok: true, ... } or { ok: false, reason, decisionTrace }. Policy refusals are never exceptions.

Testnet-only. RPC URL is loaded from env and checked against the allowlist at construction. No mainnet paths exist in any build.

Mnemonics never leave env. Loaded from env vars, never logged, never included in errors, MCP responses, receipts, or card output.

MCP surface. Every build ships an MCP server with stdio transport, strict zod validation, and base-unit digit strings for amounts (JSON numbers corrupt bigints).

---

Testnet status

Probed against node2.demos.sh, 2026-07-06:

Operation	Status
demos.run.attest.dahr	✅ Live — caller not debited (server-side fee)
demos.run.escrow.send	✅ Live — fee: 2 DEM
demos.run.attest.github	✅ Live (pending gist proof setup)
Identities.getWeb2Identities	✅ Live
Identities.getHumanPassportScore	⚠️ Requires HUMAN_PASSPORT_SCORER_ID node config
Identities.getNomisScore	⚠️ Requires EVM address linked on-chain
demos.run.d402.pay	⚠️ Node-gated — d402 not yet enabled on node2.demos.sh

---

Denomination

All amounts are bigint OS base units throughout the series. 1 DEM = 1,000,000,000 OS. Use osToDem from @kynesyslabs/demosdk/denomination for display only; never convert to Number for arithmetic.

---

Develop

Each build is an independent repo. Clone and run:

pnpm install
pnpm test         # unit tests — no network
pnpm smoke        # live probe against testnet (needs env vars)
pnpm build

CI (lint + typecheck + unit) runs on every push. Integration tests (pnpm test:integration) require funded testnet wallets and TESTNET=1.

---

Kynesys Labs — docs.kynesys.xyz