Architecture — TradeWave Bond

01 · Lifecycle

An explicit state machine, not a workflow engine

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 counterparties.

Contract Lifecycle State Machine Diagram

DRAFT: Terms proposed. Tranche percentages, conditions and nominated attesting parties are defined but not yet agreed by all sides. Freely editable.
AGREED: All counterparties have signed the tranche schedule. The schedule becomes immutable; any change requires an amendment that returns the contract to DRAFT.
FUNDED: The partner institution has confirmed that the full contract value is on deposit in a segregated account. Until this confirmation is received, no milestone can open.
MILESTONE_OPEN: Exactly one tranche is accepting evidence. Attestations submitted against any other tranche are recorded but not evaluated. Tranches cannot be skipped or reordered.
HELD: A counterparty has raised an objection before release. All automatic evaluation stops and the contract waits for an off-system resolution. This state has no timeout.
INSTRUCTED: Conditions satisfied and no hold in force. A settlement instruction has been emitted to the partner institution and acknowledgement is pending.
CLOSED: Every tranche has been released or cancelled. The event log is sealed and exported as an audit package. Terminal state.

02 · Evidence

What counts as proof, and what it actually proves

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.

Attestation fields and validation rules
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; client values are stored for reference only.

Cryptographic verification proves a specific known party signed a specific document, and that the document has not changed since. It does not certify the physical truth of the statement. See open problems.

03 · Interoperability

Proposed settlement instruction

The intention is to express release instructions in a form partner institutions can map onto ISO 20022 pacs.008 without bespoke integration work. The structure below is a design draft.

Proposed schema — illustrative application/json

// Illustrative JSON structure for settlement handoff
{
  "instruction_id": "twb_inst_01H9Z4QK",
  "contract_ref": "TWB-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 remains the partner institution's decision."
  }
}

Amounts are strings to prevent floating-point precision loss. There is no public API endpoint today; production schemas will be documented as institutional integrations finalize.

Separation from custody

The deliberate architectural constraint is that this software never holds balances. It evaluates conditions, maintains the event log, and produces instructions. A licensed institution holds the funds in a segregated account and executes instructions.

This architecture ensures that TradeWave does not require money transmitter licensing during development, and guarantees that technical issues within this software layer cannot place counterparty capital at direct risk.

04 · Open problems

What this design does not solve

These are unresolved issues we actively discuss with trade advisors and potential integration partners.

Verification is not truth

A cryptographic check confirms that a known key signed a specific document. It does not confirm physical loading of cargo. Collusion between counterparty agents defeats any verification engine. The architecture shifts fraud from deniable to attributable.

Disputes have no algorithmic answer

HELD is a state with no automated exit condition inside the software. Partial performance, goods damaged in transit, and contested specifications require external legal arbitration, not a boolean code switch.

Timing and currency risk

Prefunding tranches means buyer capital sits idle across shipping cycles. When the contract currency differs from functional currencies, exchange exposure must be carried between releases.

Key management in freight environments

The protocol assumes signers manage private keys responsibly. Practical key distribution, loss recovery, and rotation across global freight surveyors remain complex operational hurdles.

Regulatory scope

Orchestrating conditional release schedules across various US and international jurisdictions requires rigorous legal perimeter evaluation, even under non-custodial operating models.

Settlement rail finality

Payment rails differ in transaction finality and recall rules. Reconciliation between instruction emission and actual account crediting requires two-way institutional telemetry.