@kashscript/trade-sdk

Five sovereign blueprint paradigms. One Solidity factory. Zero stranded funds.

The Kash-Trade Suite is a production-grade smart-contract framework for on-chain commerce: one-time deal closure, subscriptions, escrow, English auctions, and milestone-based payouts — all sharing a single EIP-1167 minimal-proxy factory, a hardened EIP-712 signal layer, and a two-tier governance model.

bun add @kashscript/trade-sdk viem zod

Quickstart — 5-line OTDC

import { TradeManager } from "@kashscript/trade-sdk/core";

const manager = new TradeManager({ publicClient, walletClient, chainId: 8453, factoryAddress });
const trade   = await manager.deploy({ manifest, overlay });
await trade.lockFunds({ amount: 10_000_000n });        // 10 USDC
const status  = await trade.getStatus();               // { state: "Locked", ... }
const cancel  = trade.onStateChange((e) => console.log(e.currentName));

manifest is the Phase-2 hydrator-validated JSON, overlay is the DID → EOA address map. The factory deploys + initializes the clone in one atomic tx; the address is deterministic from keccak256(manifest).

Architecture

                    ┌────────────────────────────────────────┐
                    │       Phase-2 Hydrator (TS + Zod)      │
                    │   manifest.json  →  tradeHash + JCS    │
                    └──────────────────┬─────────────────────┘
                                       │
                                       ▼
                ┌──────────────────────────────────────────────┐
                │      TradeForge.sol (CREATE2 factory)        │
                │   forgeTrade(tradeHash, type, initData)      │
                │   • deterministic addressing                 │
                │   • registry of 5 paradigm implementations   │
                │   • EIP-1167 clone deployment (45k gas)      │
                └─────┬──────────┬──────────┬──────────┬───────┘
                      │          │          │          │
              ┌───────▼──┐ ┌─────▼────┐ ┌───▼────┐ ┌───▼────────┐
              │ OTDC     │ │ Escrow   │ │ Auction│ │ Milestone  │
              │ Trade    │ │ Trade    │ │ Trade  │ │ Trade      │
              └───────┬──┘ └─────┬────┘ └───┬────┘ └───┬────────┘
                      │          │          │          │
                      └──────────┴───┬──────┴──────────┘
                                     ▼
                ┌──────────────────────────────────────────────┐
                │           BaseTrade.sol (abstract)           │
                │   • non-custodial Vault accounting           │
                │   • two-layer governance (Validators+Guards) │
                │   • Phase-7-A safe disburse (no DoS)         │
                │   • EIP-712 signal verification (9 axes)     │
                └──────────────────────────────────────────────┘

                            ┌──────────────────────────┐
                            │   TradePaymaster.sol     │ ◄── ERC-4337 v0.7
                            │  (sponsored gas, drain   │
                            │   protection per trade)  │
                            └──────────────────────────┘

The five paradigms

| Paradigm | Flow | Use case | |---|---|---| | OTDC | lock → quorum.settle → terminal | Two-party fixed-price escrow with delivery attestation | | Escrow | lock → release \| dispute → resolve | Simple escrow with optional arbitrator branch | | Subscription | deposit → releaseCycle(N) → cancel(notice) | Recurring payments with per-period validation + grace period | | Auction | placeBid → endAuction → settle | English auction with soft-close (anti-snipe) ladder | | Milestone | lock → releaseMilestone(i) → finalize | Multi-stage payouts with per-step dispute isolation |

Every paradigm shares:

• ✅ EIP-1167 deterministic deploys (45,000 gas per clone)
• ✅ Phase-4-A EIP-712 signal binding (chain, clone, trade, intent, deadline, signer)
• ✅ Phase-4-B Guardian multi-sig override path
• ✅ Phase-7-A safe disburse (one hostile recipient cannot block the rest)
• ✅ ERC-4337 sponsorship via TradePaymaster

CLI

# Hydrate manifest → predict → forge + initialize, atomic
kash-trade deploy --manifest trade.json --chain 8453 --factory 0xF0…  --key $KEY

# Read-only FSM dashboard (no signer required; public-RPC fallback)
kash-trade status --address 0xCLONE… --chain 8453 --watch

# Local EIP-712 signing (validator quorum, governance override, dispute vote)
kash-trade sign --address 0xCLONE… --action settle --chain 8453 --private-key $KEY

Three commands cover the operator surface; the sign output is a JSON envelope that pipes cleanly into a quorum-aggregator daemon.

TypeScript surface

| Module | Purpose | |---|---| | @kashscript/trade-sdk/core | TradeManager + TradeInstance — high-level bridge | | @kashscript/trade-sdk/types | Strict TS interfaces for every paradigm | | @kashscript/trade-sdk/validation | Zod schemas mirroring on-chain invariants | | @kashscript/trade-sdk/utils | hydrateManifest() — Phase-2 trust boundary | | @kashscript/trade-sdk/signals | EIP-712 signal builder + QuorumBuilder | | @kashscript/trade-sdk/aa | ERC-4337 v0.7 UserOp builder + bundler client + sponsorship router | | @kashscript/trade-sdk/registry | Multi-chain registry (9 chains baked in) | | @kashscript/trade-sdk/benchmarks | Gas + finality measurement tools |

Solidity surface

| Contract | Role | |---|---| | BaseTrade.sol | Abstract base — Vault accounting, FSM, signal verify, governance, safe disburse | | ITrade.sol | Shared interface: enums, manifest struct, events, errors | | BPSSplitter.sol | Zero-dust BPS payout library | | SignalValidator.sol | EIP-712 verification + M-of-N verifyQuorum | | OTDCTrade.sol | One-time deal-closure blueprint | | EscrowTrade.sol | Two-party escrow blueprint | | RecurringTrade.sol | Subscription blueprint | | AuctionTrade.sol | English auction blueprint | | MilestoneTrade.sol | Milestone blueprint with per-step dispute isolation | | TradeForge.sol | EIP-1167 + CREATE2 factory | | TradePaymaster.sol | ERC-4337 v0.7 Verifying Paymaster |

Security posture

| Property | Status | |---|---| | Phase-7-A formal verification | ✅ audit/formal-verification.md | | Money-Lock invariant proof | ✅ 4 theorems in Appendix Θ of the spec | | Critical findings | 1 (C-1, multi-recipient DoS) — closed by Phase-7-A patch | | Suite security score average | 8.8 / 10 | | Reentrancy | All external entry points guarded by nonReentrant | | Signature malleability | EIP-2 + Phase-7-A zero-component rejection | | Drainage protection (paymaster) | Two-layer: verifier-signed + on-chain per-tradeId quotas |

Verification

# TypeScript-side vibe check (5 hydrator scenarios)
bun run verify

# Full-lifecycle simulation (Milestone deploy + 3-of-5 quorum + BPS split)
bun run vibe-check

# Gas baseline
bun run src/benchmarks/GasMonitor.ts

# Foundry tests (requires forge-std)
forge test

Multi-chain support

The static registry covers 9 chains out of the box:

| ChainId | Name | Block time | |---:|---|---:| | 1 | ethereum | 12 s | | 10 | optimism | 2 s | | 8453 | base | 2 s | | 137 | polygon | 2 s | | 42161 | arbitrum-one | ~0.26 s | | 42170 | arbitrum-nova | ~0.26 s | | 11155111 | sepolia | 12 s | | 84532 | base-sepolia | 2 s | | 31337 | anvil-local | 1 s |

For unknown chains, pass factoryAddress + registryOverlay to TradeManager.

Versioning

This is @kashscript/[email protected]. The on-chain Solidity layer is frozen pending an external security audit (Phase 7-C). The TypeScript public surface (/core, /signals, /utils, /types) is stable across alpha versions; the /aa and /benchmarks surfaces may evolve.

License

SEE LICENSE IN ../../docs/legal/SSLA.md — KashScript Sovereign-Software License Agreement, restricted-access tier.

Links

• Full specification — 2,829 lines, 8 appendices
• Formal verification report — Phase 7-A
• Performance baseline — frozen gas/finality numbers
• KashScript Foundry — the broader ecosystem