Mode 3: single-phase instruction

The issuer needs the asset transferred to it, or needs to transfer and burn it in a single atomic operation, before it can complete the burn.

Current availability: Design

Planned mechanism shapes

Planned Mode 3 mechanism shapes

Shape	Preference	When it fits
3C: atomic transfer and burn	Preferred	A smart contract can transfer and burn in one transaction.
3B: pre-authorise, then transfer	Our default recommendation	An API can validate the request before any funds move.
3A: transfer, then instruct	Fallback	The issuer has to receive the tokens before it will accept a burn instruction. This needs full recovery machinery.

What triggers a refund

The engine design has two refund triggers for Mode 3, which will apply once it's enabled:

Expiry. The burn instruction reaches its expiresAt deadline (which the engine passes through IssuerAdapter.instructBurn) without a final result. The engine then calls the issuer's refund endpoint.
Rejection after transfer. If the issuer returns InstructionRejected after the tokens have already been transferred, the engine can't unwind automatically the way it would in Mode 2. It calls the refund endpoint instead.

The engine code for both triggers will arrive with the Mode 3 implementation. These two triggers come from the plan, so please confirm with engineering before you build your refund endpoint.

Mode 3 needs full recovery machinery

When tokens are transferred before the instruction, there's a window where they've moved but haven't been burned yet. Mode 3 therefore needs a few things in place: recognising transfers idempotently, a way to return or refund tokens, an expiry policy, and reconciliation for tokens that were transferred and never burned. Every Mode 3 issuer will need a refund endpoint and a recovery-status resource before that profile can go live.

Allowances and transfers

Giving an issuer permission to pull tokens doesn't move any balance by itself. If nothing is transferred before the burn, Nuvanté treats the issuer as Mode 2, even if the issuer calls its mechanism a delegated transfer.

Sandbox availability

The plan is to ship Mode 3 in the order 3C, 3B, 3A (pending D-10). We'll point issuers towards 3B (pre-authorise, then transfer) by default. 3A is planned as a fallback with full recovery machinery, and we'll only use it when the other shapes won't work.

Mandatory refund endpoint

Every Mode 3 issuer will need to implement a refund endpoint in addition to the mint and burn instructions. It's there to close the gap where tokens have been transferred but not burned. D-10 tracks where the implementation stands. Here's an illustration of the request and response once the path is enabled:

Code sample

POST https://{issuer-api}/treasury/refunds

{
  "transactionId": "e7a1c3f5-9b2d-4e6f-8a0c-2b4d6f8a1c3e",
  "reason": "instruction_expired",
  "refundToWalletId": "wallet_source_original"
}

Code sample

200 OK

{
  "transactionId": "e7a1c3f5-9b2d-4e6f-8a0c-2b4d6f8a1c3e",
  "status": "refunded",
  "refundTxHash": "5f2c8a9e...",
  "refundedAt": "2026-09-01T10:04:12.000Z"
}

Recovery visibility

Participants and issuers can check recovery state for themselves, without contacting support:

Code sample

GET https://sandbox-api.nuvante.io/api/v1/transactions/{id}/recovery-status

Code sample

200 OK
{
  "data": {
    "transactionId": "e7a1c3f5-9b2d-4e6f-8a0c-2b4d6f8a1c3e",
    "recoveryState": "refund_confirmed",
    "preBurnTransferAmount": "100100.00",
    "refundedAmount": "100100.00",
    "timeline": [
      { "state": "transferred_awaiting_instruction", "at": "2026-09-01T09:58:00.000Z" },
      { "state": "instruction_expired", "at": "2026-09-01T10:03:00.000Z" },
      { "state": "refund_requested", "at": "2026-09-01T10:03:05.000Z" },
      { "state": "refund_confirmed", "at": "2026-09-01T10:04:12.000Z" }
    ]
  }
}