Skip to main content
Shield Swap distributes authority across the transaction signer, record owners, the protocol admin, the investigator account, token programs, and the upgrade path. These roles have different powers and should be held, monitored, and documented separately.

​
Boundary map

​
Deployer and investigator concentration

The program assigns the same initial address to DEPLOYER and SWAP_INVESTIGATOR_KEY. Initial deployment therefore concentrates:
  • Administrative authority
  • Investigator-record ownership
  • Potential access to all compliance plaintext for that account
The production impact depends on custody. Separate internal services do not create cryptographic separation if they share the same underlying account view or private key. Initial administration and investigator access use the same address. Role separation requires a different deployed design and key-custody arrangement.

​
Admin boundary

The constructor writes the hardcoded deployer address into the admin mapping for edition zero. The code comment says the program owner is enforced as that deployer, but the constructor body does not assert self.program_owner == DEPLOYER. Routine admin functions capture self.caller and compare it with the mapping. Admin powers include:
  • Fee-tier and tick-spacing registration
  • Fee-to-spacing binding
  • Write-once token-decimal registration
  • Pool enable and disable
  • Pool-creation gate
  • Token eligibility
  • Global, token, and pair pauses
  • Position freeze and unfreeze
  • Protocol-fee configuration and collection
  • Two-step admin transfer
The admin cannot use the core program to transfer an LP’s position value to itself. Position freeze can immobilize value and remove active liquidity until unfreeze.

​
Investigator boundary

The investigator address is a source constant, not a mapping. No admin function rotates it. The investigator can decrypt records for:
  • Mint
  • Single-hop swap
  • Multi-hop swap
The investigator does not receive AMM records for later position operations or claims. Its account address is known from source, but record contents remain encrypted. Admin transfer and investigator custody are independent. A new admin does not become investigator, and the original investigator does not lose record access.

​
Signer and caller boundary

self.signer is the top-level account. self.caller is the immediate invoker and can be a program. Compliance records retain both values. Integrations must preserve them as separate fields rather than collapsing them into a single actor. The signer address is account-level evidence. External systems must establish customer identity, beneficial ownership, institutional authority, and policy status.

​
Record-owner boundary

Position and token records are controlled through Aleo record ownership.
  • Mint recipient owns the PositionNFT.
  • Position operations consume and reissue that record.
  • Token change records return to the token-record owner under the token program’s implementation.
  • Collect token records go to the immutable private withdrawal address in the consumed PositionNFT.
  • Claim token records go to self.signer.
  • Compliance records go to SWAP_INVESTIGATOR_KEY.
One transaction can involve different owners. For example, the signer can fund a mint whose PositionNFT recipient is another address.

​
Blinding-secret boundary

The private blinding factor is required to reproduce the signer-bound public address for claim. The AMM does not store or recover it. The TypeScript client derives the factor from the account view key and a counter. This couples wallet record-view capability with swap-pseudonym derivation. Production wallets should decide whether that coupling is acceptable and document backup, concurrency, and compromise behavior. The public used-address mapping prevents a second successful swap with the same confidential address. It does not restore lost secrets or prevent two prepared transactions from racing.

​
Token-program boundary

The AMM dynamically invokes token programs through IARC20. The AMM trusts the selected program to implement compatible semantics for:
  • Private-to-public transfer
  • Public-to-private transfer
  • Public transfer
  • Record ownership
  • Amount accounting
  • Failure and freeze behavior
The token allowlist is an admin admission decision. It does not inspect program code or prove issuer-policy compatibility. The included wrapped_usdcx targets a test stablecoin dependency. Its bridge calls the underlying program, while its internal ARC-20 transfers do not consult the underlying freezelist on every movement. Verify production USDCx behavior end to end before enabling a market.

​
Upgrade boundary

For program editions greater than zero, the constructor checks a completed signing operation in test_shield_swap_multisig_core.aleo. The multisig constructor check applies only to upgrades. Routine pool, pause, fee, freeze, and admin-transfer calls are authorized by the deployed admin address. The dependency name includes test_, and program.json points to a local multisig program. Production documentation needs the actual deployed governance dependency and its operating policy.

​
Mutable-state boundary

Public mappings expose current state, not a complete immutable control log.
  • Admin acceptance removes the pending entry.
  • Claim removes the pending swap output.
  • Burn removes the position.
  • Unfreeze removes the freeze entry and stored height.
An independent indexer is required for durable audit history. The indexer becomes another trust boundary and needs source-version tracking, reorganization handling, completeness monitoring, and retention controls.

​
Failure scenarios

​
Admin-key compromise

An attacker can change operational settings, pause markets, freeze positions, redirect protocol-fee collection within permitted balances, and initiate admin transfer. The attacker does not automatically decrypt compliance records unless the same underlying key controls both roles.

​
Investigator view-key compromise

An attacker can attempt to discover and decrypt records owned by the investigator account. There is no ordinary in-contract rotation for future records.

​
Investigator private-key compromise

Private-key compromise includes record decryption and broader account-control risk.

​
Blinding-state loss

A trader may be unable to reproduce the relation required to claim a pending swap output.

​
Token-program failure

The AMM can fail to fund, settle, collect, or claim if the token implementation rejects calls or does not match the expected interface. Issuer and wrapper restrictions can change the practical exit path.

​
Indexer failure

Historical freeze, claim, burn, and admin evidence may be missing even though live mappings appear correct.

​
Production control requirements

Before launch, document and test:
  • Separate admin and investigator custody, or an explicit acceptance of concentration
  • Investigator loss and compromise response
  • Admin recovery and transfer
  • Upgrade authorization
  • Blinding-state backup and concurrency
  • Record discovery and spent-state tracking
  • Historical state indexing
  • Token admission and wrapper review
  • Identity binding
  • Disclosure authorization and logging
  • Pause and freeze runbooks