Skip to main content

Custody gateway deposit and withdrawal stages

Every stage a custody gateway deposit or withdrawal can be in, what the client and the operator see, who moves it and which time limit applies.

A gateway deposit and a gateway withdrawal each move through a fixed set of stages. The gateway emits DepositStageChanged and WithdrawalStageChanged on every move. The names below are the names those events carry. The concept page explains the model, and the how-to walks the routes that move a record.

The “Client sees” column is the wording in the Investor portal and “Operator sees” is the wording in the Console. A stage that rests waits for a person or a time limit. A stage that ends never moves again.

Deposit stages

Stage
Client sees
Operator sees
Rests or ends
Moved by, with the call and event
Time limit
None
Nothing
Nothing
Not a stage. No deposit has this id.
The keeper records a deposit and the gateway emits DepositRecorded with its first stage.
None
Quarantined
“In review”
“Quarantined, awaiting screener”
Rests
Entered when the keeper records the transfer. The screener leaves it with clear or refuse. The client leaves it with pull-back or exit. Gateway managers leave it with return.
pull-back-after opens the client's pull-back. paused-exit-after opens exit while the gateway is paused.
Frozen
“On hold”
“Frozen”
Rests
The screener or a gateway manager moves a Quarantined or AwaitingCustody deposit here with flag. Gateway managers end it with unfreeze, keep it with renew-freeze or lock it with report.
freeze-expiry ends a freeze that is neither renewed nor reported.
MintRefused
“Not credited”
“Mint refused”
Rests
clear enters it when the gateway cannot mint the receipts. The keeper leaves it with retry. Gateway managers can return or recover it.
None
AwaitingCustody
“Waiting for custody”
“Awaiting custody”
Rests
clear enters it for a coin set to wait for custody. The keeper leaves it when the custodian accepts, which settles it, or reports the custodian's return, after which gateway managers use custody-returned or recover.
custody-answer-time is the time the custodian has to accept the forward.
Settled
“Completed”
“Settled”
Ends
clear or retry mints the receipts. The custodian's acceptance settles an AwaitingCustody deposit. The gateway emits DepositSettled.
None
Returned
“Returned”
“Returned”
Ends
refuse, pull-back, exit, return or custody-returned pay the coins to the confirmed sender. returnedBy says who.
None
Recovered
“Recovered”
“Recovered”
Ends
Gateway managers move the coins to a destination they name with recover.
None

Withdrawal stages

Stage
Client sees
Operator sees
Rests or ends
Moved by, with the call and event
Time limit
None
Nothing
Nothing
Not a stage. No request has this id.
The client creates a request, which enters Requested.
None
Requested
“Requested”
“Requested”
Passes at once
Entered when the client requests or names a payout address. The gateway checks the payout address, the minimum and the daily maximum, then routes the request. A failed check returns the receipts with the reason Refused.
None
AwaitingPayout
“Waiting for payout address”
“Awaiting payout address”
Rests
Entered when receipts arrive by transfer with no payout address. The client leaves it with set-payout or cancel. Screeners and gateway managers can reject it.
payout-address-time expires the request and returns the receipts with the reason TimeLimit.
InReview
“In review”
“In review”
Rests
The screener clears screening and the gateway managers approve it. When nothing is left to clear, the request moves to AwaitingFunds. Screeners and gateway managers can reject it. The client can cancel it.
None
AwaitingFunds
“Waiting for funds”
“Awaiting funds”
Rests
The keeper's fulfil reserves the coins and moves the request to Claimable.
cancel-after opens the client's cancel. Unset or 0 means never.
Claimable
“Ready to collect”
“Claimable”
Rests
The client collects, or the keeper collects when auto-claim is on. Gateway managers can unfulfil it back to AwaitingFunds.
None
Settled
“Completed”
“Settled”
Ends
The claim pays the payout address. The gateway emits WithdrawalStageChanged and Withdraw.
None
ReturnPending
“Returning receipts”
“Return pending”
Rests
A return could not pay the receipts out, because the receiving wallet is frozen or unknown. completeReturn finishes it once the wallet can receive.
None
ReceiptReturned
“Receipts returned”
“Receipts returned”
Ends
reject, cancel, exit, a refusal, the payout address time limit or a return of a frozen request pays the receipts back. returnReason says why.
None

Notes

Frozen is not a stored stage

A freeze is a flag on a record, not a stage. A frozen deposit keeps the stage it was frozen from, and a read reports it with isFrozen set. DepositStageChanged still carries Frozen when a freeze starts or renews, and the Console's “Stage” column shows “Frozen” while the freeze is live. A frozen withdrawal keeps its stage in the same way, and the Portal shows “On hold”. Unfreezing restores the stage the record had.

The reported mark

report marks a frozen record as reported. A reported record never expires its freeze and nobody can unfreeze it. When a client's flag clears, reported records stay frozen.

returnedBy and returnReason

A deposit that ends as Returned carries returnedBy: None, Client, Screener or Managers. A withdrawal that ends as ReceiptReturned or waits in ReturnPending carries returnReason: None, Refused, Rejected, Cancelled, TimeLimit, FrozenReturn or PausedExit.

Time limits

Each limit is a setting that resolves from the gateway, then its profile, then the add-on default. The terms in force when a record was created are the terms it keeps. freeze-expiry and paused-exit-after are required on every enabled coin.

Was this page helpful?