Operations, quotes and states

Every durable financial action is an Operation. This page describes what it holds, the states it can report, and what happens when the network does not answer.

Quote

The Quote fixes the conditions shown to the user before they confirm:

• input asset and amount;
• source and destination network;
• expected output amount, where it applies;
• network_fee, provider_fee and service_fee;
• slippage;
• gas mode;
• provider or route;
• expiry;
• the version of the fee policy and of the capability manifest.

An expired route, or one that has materially changed, requires a new quote. The platform does not silently replace an accepted route with a different one, because the person who confirmed did not confirm those conditions.

Operation

The Operation keeps, among other things: the tenant, user and wallet; the canonical intent; the accepted quote; the authorization evidence; network, asset, amount and recipient; steps and legs; signature references; nonce and payload hash; the transaction hash, UserOperation hash or txid depending on the network; the ledger entries; the events; and the reconciliation result and evidence.

That list is what makes the operation answerable after the fact: who asked, under what conditions, who authorized it, what was submitted and what actually settled.

One operation can settle on several networks

A send split across networks runs one transfer per source network, and a cross-chain settlement one per side, so an operation is not always one transaction. transactions names each one with the network it settled on and, where the deployment publishes one, its explorer link. transactionHash still means one transaction on one network — the first — and transactionHashes is the same set as a flat list.

Reconcile against transactions, and read what each one cost in networkCost. Both are described in Costs and platform accounts.

Lifecycle

sequenceDiagram
    autonumber
    participant P as Partner / channel
    participant API as B2B API
    participant DB as PostgreSQL
    participant W as Worker
    participant SG as Partner signer
    participant C as Chain / provider
    participant R as Reconciler
    participant WH as Webhook
    P->>API: Create idempotent operation
    API->>DB: Operation + reservation + Outbox
    API-->>P: operation_id
    W->>SG: Sign the authorized digest
    SG-->>W: Signature + audit reference
    W->>C: Submit
    R->>C: Receipt / finality / provider state
    R->>DB: Ledger + reconciliation
    R->>WH: Durable event
    WH-->>P: Signed webhook

What each step does

1. Create idempotent operation. The request carries an idempotency key. If the same request arrives twice, the second one returns the first result instead of creating a second operation.
2. Operation + reservation + Outbox. All three are written in a single database transaction. The reservation commits the funds; the Outbox row guarantees the event exists if the change exists.
3. operation_id returned. The HTTP call ends here. Settlement has not happened yet, and the API does not pretend otherwise.
4. Sign the authorized digest. The worker sends a digest and a key reference to the Partner Signer Gateway. It does not send, and cannot read, the private key.
5. Signature + audit reference. The gateway returns the signature and a reference that records who signed what.
6. Submit. The adapter broadcasts to the network or provider.
7. Receipt, finality or provider state. The reconciler reads the external facts rather than trusting the submission.
8. Ledger + reconciliation. The financial impact is recorded only once the external facts agree with the intent.
9. Durable event. The state change becomes an event stored in the database.
10. Signed webhook. The Partner receives the event, signed so it can verify the delivery came from the platform.

The full order of steps is: validation, policy and risk evaluation, reservation, intent construction, network payload construction, authorization and signing, simulation where it applies, broadcast, observation, reconciliation and accounting, and notification.

States

An operation reports one of: accepted, prepared, signed, submitted, broadcast_unknown, confirmed, finalized, completed, failed, manual_review or refund_pending.

When the result of a broadcast is unknown

broadcast_unknown is the state for the case that matters most: the platform may have sent a transaction but did not get a conclusive answer. Retransmitting blindly is how the same amount gets sent twice.

sequenceDiagram
    autonumber
    participant W as Worker
    participant RPC as RPC / provider
    participant DB as PostgreSQL
    participant OBS as Observer
    participant CH as Blockchain
    W->>RPC: Broadcast the signed payload
    RPC--xW: Timeout / connection dropped
    W->>DB: Persist broadcast_unknown + payload hash
    OBS->>CH: Look for the transaction by hash / nonce / evidence
    alt Evidence exists
        CH-->>OBS: Transaction found
        OBS->>DB: submitted / confirmed + evidence
    else No evidence and retransmitting is safe
        OBS->>W: Reuse exactly the same artefact
    else Cannot be resolved
        OBS->>DB: manual_review
    end

What each step does

1. Broadcast the signed payload. The normal submission.
2. Timeout or dropped connection. No answer arrives. This does not mean the transaction was not sent.
3. Persist broadcast_unknown and the payload hash. The uncertainty is recorded, along with enough information to look the transaction up later.
4. Look for the transaction. The observer searches by hash, nonce, sender, signed payload and on-chain state.
5. If evidence exists, the operation moves forward with it. The transaction did go through.
6. If there is no evidence and retransmitting is safe, exactly the same signed artefact is reused — never a newly built one, because a rebuilt payload with a different nonce is a second transfer.
7. If it cannot be resolved either way, the operation goes to manual_review. A person decides, instead of the system guessing with someone's money.