Design document · revision 0.4.2
How the release logic is modelled, what the system treats as evidence, what it hands off to regulated institutions, and which parts of the design are still unsolved.
01 · Lifecycle
A contract occupies exactly one state at a time and can only move along defined edges. Refusing to allow arbitrary transitions makes the behaviour of the system enumerable, testable, and explainable to a counterparty evaluating trust.
02 · Evidence
Each milestone names a document type and the party entitled to produce it. On submission the system computes a SHA-256 digest of the document, verifies the submitter's signature against the key registered for that party at contract agreement, and records the result.
| Field | Type | Rule |
|---|---|---|
milestone_id |
UUID | Must reference a tranche currently in MILESTONE_OPEN. |
document_digest |
SHA-256, hex | Recomputed server-side; the submitted value is compared, never trusted. |
attestor_key_id |
Key reference | Must match a key registered to the nominated attesting party at AGREED. |
signature |
Ed25519 or ECDSA P-256 | Verified over the digest and milestone identifier together, to prevent replay of a valid attestation against a different milestone. |
submitted_at |
RFC 3339 | Server timestamp is authoritative; the client value is stored for reference only. |
The honest summary: this proves a specific known party asserted a specific document, and that the document has not changed since. It does not prove the assertion is true. See open problems.
03 · Interoperability
The intention is to express release instructions in a form a partner institution can map
onto ISO 20022 pacs.008 without bespoke integration work. The structure below
is a design sketch. It has not been validated against the ISO schema and no institution
has reviewed it.
// Not a live API. Field names and nesting are provisional.
{
"instruction_id": "swb_inst_01H9Z4QK",
"contract_ref": "DEMO-2026-084",
"created_at": "2026-09-15T09:41:22Z",
"milestone": {
"index": 2,
"condition": "customs_entry_accepted",
"attestor_key_id": "key_broker_4f1b",
"document_digest": "9f2c...a731"
},
"amount": {
"currency": "USD",
"value": "200000.00"
},
"execution": {
"mode": "partner_institution",
"note": "Rail selection is the institution's decision, not ours."
}
}Amounts are strings to avoid binary floating point. There is no public API endpoint today; when one exists it will be documented here with real authentication requirements.
The deliberate architectural constraint is that this software never holds a balance. It evaluates conditions, maintains the event log, and produces instructions. A licensed institution holds the funds in a segregated account and decides whether to act on an instruction.
That choice costs latency and adds a dependency we do not control. It buys something more valuable at this stage: the initiative does not need a money transmission or trust licence to be built and evaluated, and a failure in this software cannot put anyone's money at risk.
04 · Open problems
These are the unresolved issues we want partners and advisors to press us on. Listing them is not modesty; it is the fastest way to have a useful conversation.
A cryptographic check confirms that a known key signed a specific document. It says nothing about whether the container was actually loaded, or whether the surveyor inspected anything. Collusion between a buyer and a nominated attestor defeats the system entirely. The realistic framing is that this shifts fraud from deniable to attributable — a liability improvement, not a prevention mechanism.
HELD is a state with no exit condition inside the software. Partial performance, goods that arrive damaged, and milestones that are half-met are all normal in trade, and none of them reduce to a boolean. Without a credible arbitration path attached to the contract, an automated release schedule can lock funds as easily as it frees them.
Full prefunding means the buyer's capital sits idle across a shipment cycle that may run for months, which is the exact cost that letters of credit exist to avoid. Where the contract currency differs from the parties' functional currencies, someone carries that exposure between tranches. Neither problem is addressed in this design.
The model assumes attesting parties control their signing keys and that those keys can be rotated or revoked mid-contract. In practice a freight surveyor is not running a key ceremony. Key distribution, loss recovery and revocation semantics are unspecified and are probably harder than the settlement logic itself.
Even without touching funds, orchestrating conditional releases may bring the project within escrow, payment initiation or money transmission regimes depending on the jurisdiction, and those regimes differ by US state as well as by country. This requires formal legal classification as the architecture matures.
Payment rails differ in whether and for how long a transfer can be reversed. A ledger that marks a tranche settled the moment an instruction is emitted will drift from reality. Reconciliation against actual settlement confirmation, and the handling of returns and recalls, is not yet modelled.