Skip to main content
Shield Swap has seven integration layers. A production application normally touches at least four of them.

​
Layers

​
Program execution

shield_swap.aleo contains the AMM state machine. User functions validate inputs and construct records or a Final. Finalizers execute token futures and update public mappings. The program imports multisig, freezelist, and a pinned IARC20 interface. A field identifier selects the concrete token program at runtime. The core accepts protected calls from only the hardcoded swap, LP, and rebalance router addresses. Successful interface dispatch does not prove that a token is safe or operationally approved. Asset support depends on the deployed token program’s code, state, transfer behavior, and authority model.

​
Public state and record ownership

Mappings contain pools, slots, ticks, positions, pending swap outputs, configuration, and controls. They support quoting, indexing, and independent accounting. They also expose amounts, routes, ranges, liquidity, fees, timing, and control actions. Records carry a different kind of state:
  • token records carry spendable value
  • PositionNFT carries position authority
  • investigator records carry encrypted mint, rebalance, or swap attribution
A public position row does not prove wallet ownership. A PositionNFT alone does not contain the position’s latest public economics. Clients must reconcile both.

​
Swap data flow

  1. The client reads current pool, tick, token, and control state.
  2. The client preflights a revisioned protocol snapshot and the wallet selects an input token record.
  3. The client selects direct swap, swap_from_wrapped, or swap_mh_from_wrapped from the asset registry.
  4. The program moves input value into public custody and updates AMM mappings.
  5. Finalization writes swap_outputs[swap_id].
  6. The client reads that exact output and constructs the current core or router claim with signer proofs.
  7. The program returns output and refund token records.
  8. The wallet stores the records and reconciles the final public state.
A pending swap_outputs entry is an unsettled user obligation until claim removes it.

​
Position data flow

Mint creates a public position and a PositionNFT that binds owner and immutable withdrawal address. Mint, rebalance, collect, and claim require current non-inclusion proofs. Increase, decrease, and collect return a replacement record for the same token ID. Burn removes the public row and consumes the final ownership record. Rebalance removes the complete old position and creates a new token ID and record. It keeps the pool and withdrawal address and makes the signer the owner. Custody systems must update record inventory only after transaction acceptance is known.

​
Production client boundary

The TypeScript harness demonstrates mapping reads, parsing, record handling, submission, and persistence. It is test-oriented. A production client still needs:
  • a quote engine that matches contract rounding and iteration caps
  • a record store with reserved, spent, and unknown states
  • a pending-claim queue
  • deployment-versioned parsers
  • a chain indexer or API client
  • bounded retry and finality handling
  • durable reconciliation and monitoring
Continue with Transaction execution for client state, or Protocol boundaries for ownership across systems.