Execution lifecycle
After your wallet performs the plan steps, the trade moves through a small set of states. The SDK derives them from the taker's own ledger view; a planned server-side status endpoint will report the same states.
The states
| state | terminal | what it means for the user |
|---|---|---|
INITIATED | no | The deposit offer is out, funds are committed but still in the user's wallet (a Canton transfer proposal), waiting for the venue. |
VENUE_ACCEPTED | no | The venue took the deposit; the payout is in flight. Observed Tradecraft timing: acceptance in seconds, payout in minutes. |
COMPLETED | yes | The payout arrived and meets the floor (payout >= minReceive). Fee legs settle. |
SLIPPAGE_FAILED | yes | The outcome broke the floor: either the venue rejected on the minimum (deposit consumed, no payout) or a payout arrived below it. Surfaced honestly; the fee escrow is NOT released. |
REFUNDED | yes | Nobody accepted before expiry; the offer auto-expired and the funds returned to the user's wallet. No fees are taken on a refund. |
ABORTED | yes | The integration withdrew the still-active offer before acceptance (user cancel). Funds never left. |
There is also a transient EXPIRED observation: the deadline passed
with the offer still out, awaiting the ledger's auto-expiry; it resolves to REFUNDED. There is deliberately no partial-fill state: Canton venue settlement is
all or nothing.
Refund semantics
The deposit is a Canton transfer proposal: it sits in the user's wallet
until the venue accepts and expires back automatically if it does not. The
user is never waiting on Synfin, or on the venue's goodwill, to get a
refund; expiry is a ledger mechanic. On REFUNDED and
ABORTED, no fee is collected.
The floor guarantee, per venue
The plan's minReceive floor is only as strong as who enforces it.
Stated honestly:
| venue | floor enforcement |
|---|---|
| Tradecraft | Venue-enforced. The floor travels in the deposit memo and Tradecraft honors it at execution: a trade that would break it is rejected, not filled worse. |
| Venues that do not bind a floor | SDK-enforced, post-hoc. The SDK compares the observed payout
to the floor and surfaces SLIPPAGE_FAILED; the fee
escrow is not released. The user learns the truth, but the fill
itself is not prevented. Execution for such venues ships only with
this caveat stated. |
Execution v1 supports Tradecraft. Every future venue's row will state which of the two guarantees it actually provides.