Failures and recovery

Recovery starts by identifying the order’s actual on-chain phase. Do not retry from an error string alone.

​

Classify the phase

If submission status is unknown, keep the input record reserved until its commitment state and transaction outcome are confirmed.

​

Pre-submit failures

These should be caught before proving or broadcasting:

​

No sufficient token record

The AMM consumes one input record. Acquire a larger record through the token program or select a different amount. Do not attempt to pass several records.

​

Wrong token record

Compare the record’s concrete token program with canonical pool token order and direction. Symbols and API metadata are not sufficient.

​

Base-unit amount is invalid

Parse the user’s decimal input into an exact integer using the token metadata decimals. Reject a fractional base unit or a value outside u128.

​

Invalid price limit

Refresh the slot and require a limit strictly below current price for zero_for_one or strictly above it for one_for_zero. A limit equal to current price is invalid.

​

Economically empty dust trade

If fee flooring reduces effective input to zero, the trade produces no output and returns the input. Raise the amount or decline the order.

​

Swap rejection

Common finalize rejection causes include: A rejected order should not create a usable pending output. Before reusing its input record, confirm rejection and record spend state with chain data. Client timeouts are not proof of rejection.

​

Accepted partial execution

An accepted swap can leave input unspent while still meeting amount_out_min. The claim returns that remainder in a token record. Possible causes include:

• Price limit reached
• Five-iteration single-hop cap reached
• Three-iteration per-hop multi-hop cap reached
• Zero effective input after fee flooring

Read swap_outputs and show the original-input remainder. Do not automatically submit another swap for it. The user should receive the refund record, review current state, and authorize any follow-up order.

​

Accepted swap with no claim

If the swap is accepted, recovery is a claim, not a repeated swap.

1. Extract or reconstruct swap_id from the accepted transition output.
2. Read swap_outputs[swap_id].
3. Recover the original signer and private blinding factor.
4. Submit claim_swap_output with exact mapping values and current signer freezelist proofs.
5. Confirm mapping removal.
6. Decrypt and store returned token records.

Trading pauses do not directly block claim finalizers. Diagnose a failed claim from the pending mapping and token-transfer result.

​

Claim rejection

​

Confidential address mismatch

Use the same signer and factor that created the confidential address. A new factor cannot be substituted after the swap.

​

Mapping value mismatch

Read the mapping again and copy every token and amount exactly. Do not use quoted output or a rounded display amount.

​

Wrong router claim

Both core swap paths use claim_swap_output. If an output or refund is wrapped, select the matching shield_swap_router.aleo claim adapter from the deployment asset registry.

​

Output already claimed

If the mapping is absent, inspect the prior claim transaction and local record scanner. Repeating the claim cannot recreate the removed entry.

​

Token transfer failure

Confirm the concrete token programs, amounts, deployment availability, and record output handling. The AMM mapping may remain present after a rejected claim, allowing a corrected retry.

​

Lost blinding recovery material

The normal claim path requires the original signer and private factor. The protocol does not provide an administrator recovery or redirect function for pending swap outputs. Wallets should persist encrypted recovery material before swap submission and include it in backup procedures. Investigator-owned compliance records support authorized attribution but are not spend credentials.

​

Missing output records

If the claim is accepted but the wallet shows no funds:

1. Confirm the pending mapping was removed.
2. Retrieve the accepted claim transaction outputs.
3. Enumerate record, dynamic-record, and dynamic-ID record outputs.
4. Decrypt with the signer’s view key.
5. Preserve _version and _nonce when parsing.
6. Match each record to its concrete token program.
7. Rebuild the local record index without rebroadcasting the claim.

Verify confidential settlement from accepted claim outputs and record decryption. Public balance changes do not show record delivery.

​

Multi-hop-specific recovery

• A route rejection is atomic. Do not assume earlier hops produced claimable intermediate assets.
• An accepted route returns final output and can return remaining original input.
• If a hop hit its iteration cap, a follow-up route begins from new public pool state and needs a new input record after the refund claim.
• A two-hop request still carries a padded third hop. Validate hop_count before interpreting route telemetry.
• Final minimum output applies to the route output, not to the original-input remainder.

​

Operational metadata failures

An off-chain token API outage can prevent a frontend from discovering symbols or constructing operator onboarding steps. It does not change an existing pool’s public token identifiers. The API seed script is separate from on-chain pool-creation allowlisting. After a metadata failure, confirm the environment, run a dry run, review each token program, and authorize on-chain actions separately.

​

Incident record

For every material failure, retain:

• Network, program ID, and edition
• Pool and route identifiers
• Transaction identifiers and terminal status
• Block heights used for quote and deadline
• Public request parameters
• Slot and relevant tick snapshots
• Local record handles, never plaintext in general logs
• Pending-output snapshot
• Client and SDK version
• Recovery action and result

When identity disclosure is required, use the approved compliance-record process. Do not mix decrypted investigator material into ordinary support logs. Return to Trader workflow after the order reaches a known terminal state.