Docs / Coordination model
Understand the coordination model
Learn the objects, trust boundaries and guarantees before connecting real agents.
One round, one resource, one asset
A round freezes a participant roster, a resource description, a payment asset and three deadlines. Quantities and amounts are canonical integer strings. Arithmetic uses bigint. A resource label can describe GPU hours, inference credits or dataset seats; it does not implement resource delivery.
| Object | Contract |
|---|---|
| Demand | A positive quantity and a total spend cap. The buyer may replace or withdraw it before demand closes. |
| Bid | A positive capacity, unit price and 32-byte salt. The commitment binds these to the round and seller. |
| Allocation | Complete buyer fulfillment within budgets and seller capacity. Split lines identify both buyer and seller. |
| Transcript | Versioned accepted commands and observation time. Replay recomputes the outcome. |
| Settlement plan | Exact amounts and stable payment IDs derived from the closed allocation. |
Time is part of the protocol
The live coordinator defaults to Date.now(), in Unix milliseconds. Windows are half-open: demand is accepted before demandCloses, commitments from demandCloses up to commitCloses, and reveals from commitCloses up to revealCloses. At a closing timestamp, a submission is late. The clock must never move backwards. Simulations supply logical timestamps instead.
What SwarmKit enforces
The SDK checks participant membership, phases, immutable commitments, reveal hashes, allocation totals, capacity and budgets. Its runner enforces supplied approvals and binds split payment plans to a journal. Applications authenticate identities, protect keys, persist state atomically and pin custom mechanism implementations.
What replay proves
A transcript can be internally consistent while omitting a submission. Replay checks the recorded inputs; it does not establish their completeness or origin. Store the transcript in a trusted service or add an external attestation layer if your application needs stronger provenance.
Current boundaries
SwarmKit currently implements procurement. It does not supply escrow, atomic all-buyer settlement, refunds, delivery verification, arbitrary negotiations, compatibility matching or a production identity provider. Python bindings and additional economic protocols remain future work. The deliveryWindow field is descriptive, not an enforced fulfillment deadline.