Order lifecycle

An order is created when the indexer sees a deposit carrying a known quote hash. Until then there is a quote but no order, and GetOrder returns the quote alone.

States

State	Meaning	Terminal
`created`	Deposit recorded, order opened.
`awaiting_finality`	Confirmations accruing on the source chain.
`ready_to_fulfill`	Finality reached, waiting for a relayer worker.
`fulfilling`	Claimed by a worker, destination transaction submitted.
`fulfilled`	Destination transaction confirmed. The user has their funds.	yes
`pending_refund`	Cannot be fulfilled: mismatched deposit, or 3 failed attempts.
`refunding`	Refund transaction submitted on the source chain.
`refunded`	Refund confirmed.	yes
`awaiting_refund_window`	A submitted transaction reverted or had its nonce burnt; the outcome is being resolved.
`refund_skipped`	Refund would cost more than the deposit is worth.	yes
`review`	Automation stopped and an operator decides. The order keeps a reason (`deposit_missing`, `refund_failed`, `payout_conflict`, `unsupported_deposit`, `verification`) and the step it resumes from. An operator retry puts it back into the normal flow with every check re-run; nothing is forced.
`support`	No automatic path can finish this order. Nothing processes it again; the funds stay in the escrow and the user contacts support.	yes

Same-chain swaps skip the middle entirely. The router performs the swap inside the deposit transaction, and the order goes to fulfilled once the finality indexer confirms it.

Collapsing states for a UI

Four outcomes are enough for most interfaces, and the SDK maps them for you:

import { orderOutcome, isTerminalState } from "@mayanfinance/blink-sdk";

orderOutcome(order.state);   // "pending" | "fulfilled" | "refunded" | "failed"
isTerminalState(order.state); // stop polling when true

failed covers refund_skipped and support: the cases where a human needs to get involved. review is still pending, because an operator retry can carry it to fulfilled or refunded. Everything not in the table above maps to pending.

Progress while pending

Two fields on the order carry real progress and are worth surfacing:

Field	Use
`src_confirmations`	Confirmations seen so far.
`required_confirmations`	Confirmations needed before fulfillment starts.

Requirements vary by chain and by trade size, so render the ratio rather than a fixed count. Once src_confirmations reaches the requirement, the remaining wait is submission and destination confirmation, which is typically seconds.

Ambiguous outcomes

awaiting_refund_window is not a failure. It means a transaction reverted or was replaced and the operator refuses to guess what landed. After a quiet period both transaction hashes are re-polled and the order moves to whichever state matches the chain: fulfilled if the fulfillment actually landed, refunded if the refund did, or back into the refund path. Treat it as pending in a UI, and keep polling.

Never treat a destination transaction hash as proof of settlement. dst_tx_hash is populated when a transaction is submitted, not when it confirms. The order state is the authority.

Signer cluster

No service that builds transactions holds a private key. Every fulfillment and every refund is signed by a cluster of seven signer nodes, each on its own server. Every key is a 5-of-7 threshold key: each node holds one share, no node ever holds the whole key, and a signature exists only after five nodes have approved the exact transaction and taken part in signing it. One node is the coordinator. The relayer talks only to the coordinator, and only the coordinator talks to the other six. All seven are run by the operator, so the cluster does not change the trust model. What it does is limit the damage one compromised server, RPC provider, or service can do on its own.

Where signing sits

Signing happens after a relayer worker claims the order and before anything is broadcast: in fulfilling for a fulfillment, in refunding for a refund. A transaction the cluster does not sign is never broadcast.

What every node checks

Each node decides on its own, using its own RPC providers, its own price feeds, and its own database.

Check	Detail
Who is asking	The vote request is signed by the coordinator, and both run the same signing policy.
Which key	The key holds a role that may sign this kind of transaction on this chain.
The deposit	It is on the quote’s source chain, carries the quote hash, matches the quote’s token and amount, and has the confirmations its size requires.
The transaction	The node rebuilds it from the quote and requires a byte-for-byte match: contract, recipient, token, amount, and gas drop. A fulfillment pays between `min_amount_out` and the quoted amount. A refund pays the quote’s refund address at least the deposit minus the committed refund fee.
The value	The payout is worth no more than the deposit minus referrer fees, priced by the node’s own feeds, and the gas fee fits inside the remaining margin.
The ledger	The node has not approved a conflicting transaction that landed or could still land: another fulfillment of the same quote, or a refund of the same deposit. A gas bump at the same nonce is allowed; a retry at a new nonce is allowed only once the earlier one is provably dead on chain.

A node that passes every check records the approval and signs its vote with its own identity key. A node that refuses only because the deposit is missing or not yet deep enough on its own providers votes unsettled instead of refuse.

Counting votes

The coordinator asks all seven nodes at once and counts votes as they arrive.

Votes	Result
The coordinator and four others approve	Approved. Remaining votes are not awaited.
The coordinator refuses	Refused at once, whatever the others vote.
Three nodes refuse or do not answer within 10 seconds	Refused, because five approvals are out of reach.

Once a request is approved, the coordinator runs the signing session with itself and the four fastest approvers. If that session fails, it tries other approvers, asking every node again if needed, for up to three sessions in total. A request that is not signed ends in one of three outcomes:

Outcome	When
`unsettled`	At least one node voted `unsettled` and no node refused.
`refused`	At least one node refused.
`unavailable`	No node refused but too few answered, or every signing session failed.

How each outcome moves the order

Outcome	Fulfillment	Refund
Signed	Broadcast. The order stays in `fulfilling` until the destination confirms.	Broadcast. The order stays in `refunding` until the refund confirms.
`unsettled`	Back to `awaiting_finality`, where the indexer re-checks the deposit on chain.	Back to `pending_refund`, retried after a cool-down.
`refused` or `unavailable`	Back to `ready_to_fulfill`, retried with a growing backoff.	Back to `pending_refund`, retried after a cool-down.

None of these outcomes counts toward the 3 failed attempts that route an order to refund. Treat all of them as pending in a UI.

Fault tolerance

Two nodes can be down. Any five of the seven, coordinator included, can sign. A third node down stops signing; it never produces a wrong signature.
The coordinator is required. It takes part in every signature. While it is down nothing is signed, and orders wait in their current state until it is back.
One bad view cannot approve a payout. Each node reads chains through its own providers and prices through its own feeds, so a compromised provider moves one vote out of seven.
Conflicting payouts need collusion. Any two groups of five share at least three nodes, so a second payout that conflicts with a signed one needs at least three nodes to approve against their own ledgers.
Repeats are safe. The coordinator stores each signature with the signed votes behind it, and an identical request gets the stored signature back without a new vote.

See Track an order for polling patterns, and Refunds for what the refund branch pays out.

Overview

Concepts

Order lifecycle

States

Collapsing states for a UI

Progress while pending

Ambiguous outcomes

Signer cluster

Where signing sits

What every node checks

Counting votes

How each outcome moves the order

Fault tolerance

​States

​Collapsing states for a UI

​Progress while pending

​Ambiguous outcomes

​Signer cluster

​Where signing sits

​What every node checks

​Counting votes

​How each outcome moves the order

​Fault tolerance

States

Collapsing states for a UI

Progress while pending

Ambiguous outcomes

Signer cluster

Where signing sits

What every node checks

Counting votes

How each outcome moves the order

Fault tolerance