Statuses, confirmations and reorgs

The life of a sweep

queued ──▶ processing ──▶ swept
   ▲            │  ├────▶ failed
   └── retry ◀──┘  └────▶ rejected

Status	Meaning
`queued`	Accepted and waiting for a batch, or waiting for a retry.
`processing`	In a batch that is being prepared, is on its way, or waits for its confirmations.
`swept`	Final. The funds are in the hot wallet: `swept_amount`, `tx_hash`, `gas`, `fee`.
`failed`	Final. The transfer reverted on chain, or the sweep ran out of attempts. `reason` says why.
`rejected`	Final. The sweep was never sent: a check before sending kept failing. `reason` says which.

attempts counts the tries. The final status comes with a sweep.swept, sweep.failed or sweep.rejected webhook event. reason is always one of the stable codes below: branch on it. The node’s own messages stay in our logs; new codes may come, so treat one you do not know like internal.

Why a sweep is rejected

Before a batch goes out, the service checks every address on one block. A sweep that fails a check is checked again after a pause, three times in all, because a node may not see funds or a delegation that have just arrived. If it still fails, the sweep is rejected:

`reason`	What happened	What to do
`not_upgraded`	The address is not delegated to this hot wallet’s delegate, and the request had no authorization.	Send the sweep again with an authorization.
`stale_authorization`	The authorization’s nonce is not the address’s nonce: the address sent a transaction after you signed.	Sign again with the current nonce.
`would_fail`	The simulation shows the transfer would fail, for example no balance or less than `amount`.	Check the address’s balance.
`nothing_to_sweep`	With `keep_one_unit`, the address holds no more than the unit it keeps.	Nothing: sweep it after the next deposit.

Why a sweep fails

failed with the name of a contract error means the transfer reverted on chain, inside a batch that went through:

`reason`	Meaning
`TokenTransferFailed`	The token refused the transfer.
`NativeTransferFailed`	The hot wallet refused the native coin.
`NothingToSweep`	The balance was gone by the time the batch executed.
`Unauthorized`	By the time the batch executed, the address was delegated to another delegate.
`reverted`	The transfer reverted without an error of our contracts, for example a token that used up the 300,000 gas one address may take.

Such a sweep bears its share of the gas but no fee. Any other reason of a failed sweep is the cause of its last attempt.

Causes of a failed attempt

An attempt can fail as a whole: for example, the batch cannot be sent while the gas wallet has no gas, or the whole transaction reverts. The sweep then goes back to queued for a retry, and reason says why until the next attempt. A sweep gets five attempts, with growing pauses between them; once they run out, it ends failed with the cause of the last one. The same causes come in a revocation’s reason and in a hot wallet’s error.

`reason`	What happened	What to do
`insufficient_gas_balance`	The gas wallet’s balance, less the fees due it keeps in reserve, does not cover the transaction.	Top up the gas wallet: queued sweeps go on by themselves.
`gas_limit_exceeded`	One sweep needs more gas than a transaction may use, for example because of an unusual token.	Contact support.
`transaction_reverted`	The whole transaction reverted, on chain or in its gas estimate.	Nothing: it is retried. If it keeps happening, contact support.
`nonce_conflict`	Another transaction took the gas wallet’s nonce.	Nothing: it is retried with the next nonce.
`chain_unavailable`	The chain’s node did not answer, or failed the request.	Nothing: it is retried.
`internal`	Something else failed on our side.	Nothing: it is retried. If it keeps happening, contact support.

Confirmations

The service records an outcome only after the transaction’s block has enough blocks on top of it: three on the testnets, counting its own block. Until then the sweep stays processing.

If a reorg drops the block within those confirmations, the transaction’s receipt disappears, and the service sends the same transaction again from its journal. You see nothing but a delay: no duplicate sweep, no lost sweep. An outcome is recorded once its confirmations are in, and a deeper reorg after that is not handled; on Ethereum and BSC such reorgs are very rare.

The service also takes care of transactions that get stuck: it sends them to the node again and, if they still wait, replaces them with the same transaction at a higher fee. You never need to resend anything yourself.

Hot wallets

Status	Meaning
`pending`	The delegate is being deployed. Sweeps to this hot wallet get `409 hot_wallet_not_active` until it is active.
`active`	The delegate is on chain: `tx_hash` is its deployment. A `hot_wallet.active` event is sent.
`failed`	The deployment did not work; `error` says why. A `hot_wallet.failed` event is sent. Send `POST /v1/hot-wallets` again to retry.

error is a code too. Most often it is insufficient_gas_balance: top up the gas wallet, then register the hot wallet again. not_deployed means the deployment went through but the delegate is not at its address: contact support. Any other code is a cause of a failed attempt.

Revocations

A revocation goes through queued and processing like a sweep, then ends as revoked, failed or rejected:

Status	`reason`	Meaning
`revoked`		The address has no delegation any more.
`rejected`	`not_delegated`	The address had no delegation to remove.
`rejected`	`stale_authorization`	The address’s nonce is no longer the one you signed for.
`rejected`	`invalid_authorization`	The authorization did not pass the check before sending. Sign again.
`failed`	`not_applied`	The transaction went through, but the chain skipped the authorization: the address’s nonce changed after the check. Sign again.
`failed`	other	The cause of the last attempt, after the attempts ran out.

See Revoking a delegation.