Issuer instruction lifecycle

Each issuer's API has its own statuses. The engine translates (normalises) them into a common set of events before they affect the settlement saga.

Normalized events

The status column shows what the saga does next for each event.

CodeSaga actionDescription

InstructionSubmittedAwaitThe issuer has accepted the request and will process it asynchronously.

InstructionAuthorisedAwaitThe issuer has approved the instruction. Nothing is final on the ledger yet.

BurnedAdvanceA verified burn proof for the source asset lets RTGS settlement go ahead.

MintedComplete legA verified mint proof for the target asset completes the mint leg.

InstructionRejectedUnwindCancel and return the locked value, as long as that's still safe.

InstructionFailedParkExecution failed, so someone needs to investigate before anything is reversed.

ParkedOnSilenceParkThe issuer's approval budget ran out without a final result.

How issuer statuses map to events

Here's how the statuses an issuer's API returns (yours included, for Mode 2 and 3) map to normalised events. Intermediate statuses don't trigger anything in the saga. The engine keeps polling until it gets a final or proof-carrying response.

Issuer statusNormalised eventDescription

RECEIVEDInstructionSubmittedThe issuer has accepted it. The saga starts polling.

PENDING_APPROVALNone (internal)Still in progress. The saga keeps polling.

APPROVEDNone (internal)Still in progress. The saga moves on to the execute call.

EXECUTINGNone (internal)Still in progress. The saga keeps polling.

COMPLETED (burn)BurnedCarries on-chain proof. Moves on to RTGS settlement.

COMPLETED (mint)MintedCarries on-chain proof. Completes the mint leg.

REJECTEDInstructionRejectedTriggers an automatic unwind.

FAILEDInstructionFailedParks the transaction for reconciliation.

(timeout)ParkedOnSilenceRaised when approvalSlaSeconds passes with no final result.

Intermediate issuer statuses

Statuses like PENDING_APPROVAL and EXECUTING can exist inside an adapter, and the saga ignores them. Nuvanté keeps polling until the adapter returns a normalised event that's either final or carries a proof.

On-chain proof

A burn or mint event names its ledger, its transaction hash and its ledger sequence (a Stellar ledger, an EVM block or a Solana slot). On ledgers with probabilistic finality, we may also check confirmation depth or finalised commitment before accepting the event.

Rejection and failure are different

A rejection means the issuer said no before completing the operation, so the engine tries to unwind automatically. If the rejection arrives after it's no longer safe to reverse things, the transaction parks.

A failure is handled more cautiously. We can't assume nothing happened on-chain, so a failure always parks the transaction for reconciliation.

Public transaction status

These events are used internally and for conformance testing. They don't add any new public transaction statuses. Keep polling the transaction resource and handle the statuses it publishes.