> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metalntwx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and Authorization Flow

> Who holds the keys, prepares proofs, and authorizes each MIP410 transaction

## Roles

### Customer

* Gives a payment instruction: who to pay, how much, and when
* Holds the spending key in their own wallet for self-custody, or entrusts it
  to a custodian
* Instructs their VASP to prepare the transaction

### Custodian

* Safeguards the customer's spending key and signs authorizations with it
* Cryptographically authorizes the transaction by signing with the key
* May be the customer's VASP. Under self-custody, the customer's wallet performs
  this signing role

### VASP

* Prepares transactions for its customers and applies the required policies
* Obtains signed authorizations from the customer's wallet or custodian and
  arranges proof construction
* May serve both sender and recipient. It holds spending keys only if it also
  provides custody

### Proving service

* Builds proofs that a transaction satisfies the circuit's checks, including
  any required signed authorization. The VASP can do this itself or delegate
  it to a separate service.
* Receives the keys, authorizations, and private inputs needed for the proof.
  For proofs that check spending-key signatures, these include the
  spend-verification key and nullifier key. It does not need the spending key.
* Can read the private inputs it receives, and identify spends of known notes
  via the nullifier key
* Cannot create a new spending authorization without the spending key.

### Submitter

* Broadcasts the prepared transaction and pays gas in a MIP20 gas token
* Can be the customer's EVM account, the VASP's account, or a relayer acting
  on their behalf
* The submitting account, gas token, and fee are public
* Needs the prepared transaction and proofs, but not the customer's
  spending or viewing keys
* Cannot change values bound by a proof or authorization, such as the amount,
  destination, or resolution decision, without invalidating it.

### MIP410 authority

* Administers the pool's shared compliance rules and participation requirements.
* Uses an EVM administrator address configured at deployment or network genesis.
* Admits and revokes VASPs and shielding assets, updates the sanctioned set,
  and controls the maximum hold duration, circuit IDs, bridge gateway, and pause.
* Can transfer administration through a two-step authority transfer.
* Has a regulatory viewing role in the design. This requires access to the
  relevant wallet's incoming viewing key, nullifier key, and payment data.
* With that access, can read payments received by the wallet and identify
  spends of known notes.

These administrative powers do not give the authority access to private
payment data or permission to spend customers' notes. The
[MIP410 reference](https://docs.metalntwx.com/reference/assets-and-payments/mip410.md#authority-registry-and-vasp-controls)
describes how the pool's administrative controls work.

### MIP410 shielded pool

* Verifies submitted proofs and checks the transaction against its current state.
* Records note commitments, holds, input locks, and spent-note nullifiers.
* Holds the public MIP20 value backing the notes and transfers it during
  shielding and unshielding.
* Executes the verified transaction without holding customers' spending or
  viewing keys.

## Authorization flow

The flows below separate customer instructions, signatures, proof construction,
and onchain execution. One provider may perform several roles: a VASP can
also act as custodian, prover, and submitter.

### Shielding

```text theme={null}
Customer
  -> asks the VASP to turn public MIP20 value into a shielded note
VASP
  -> prepares the deposit and note details
Customer's MIP20 account
  -> signs a deposit authorization allowing the pool to transfer the public MIP20 value
Customer's wallet or custodian
  -> signs the shield authorization with the spending key
Proving service
  -> builds the shield proof using the signed shield authorization
Submitter
  -> submits the shielding transaction, deposit authorization, and proof
MIP410 shielded pool
  -> verifies the proof and collects the authorized MIP20 deposit
  -> records the note commitment
```

Shielding needs two authorizations: one from the MIP20 account holding the
public value and one from the spending key that will control the note. The
same provider may manage both keys. The shield proof binds the note to the
public deposit and checks the shielded identity against the sanctions root.
The deposit and note creation succeed or revert together.

### Payment initiation

```text theme={null}
Sender
  -> instructs the sender VASP who to pay, how much, and when
Sender VASP
  -> prepares the input notes, output notes, and hold deadline
Sender's wallet or custodian
  -> signs the payment authorization with the spending key
Proving service
  -> builds the sender proof and policy-wrapper proof for initiation
Submitter
  -> submits the initiation transaction and proofs
MIP410 shielded pool
  -> verifies the proofs and checks the proposed hold
  -> creates the hold and locks the input notes
```

The signature fixes the notes to be spent and created if the recipient VASP
accepts. It also binds the payment to the intended recipient VASP, deadline,
and the chain ID, pool contract address, and state used by the proof. Initiation
reserves the input notes. They are spent only if the payment is accepted.

### Acceptance

```text theme={null}
Recipient VASP
  -> reviews the held payment and decides to accept it
Proving service
  -> builds the recipient proof bound to acceptance
  -> builds the policy-wrapper proof for acceptance
Submitter
  -> submits the acceptance transaction and proofs
MIP410 shielded pool
  -> verifies the proofs and checks that the hold is unresolved and unexpired
  -> spends the input notes and records the recipient and any change notes
```

Acceptance completes the spend already authorized by the sender. It requires
neither a new sender signature nor the recipient's spending-key signature. The
recipient proof uses the incoming viewing key and private payment data to
match the recipient note to the authorized payment. It uses registry evidence
to check that the recipient's registered VASP matches the VASP bound to the hold.

### Rejection

```text theme={null}
Recipient VASP
  -> reviews the held payment and decides to reject it
Proving service
  -> builds the recipient proof bound to rejection
  -> builds the policy-wrapper proof for rejection
Submitter
  -> submits the rejection transaction and proofs
MIP410 shielded pool
  -> verifies the proofs and checks that the hold is unresolved and unexpired
  -> marks the hold as rejected and releases the input locks
```

Rejection requires the recipient proof and policy-wrapper proof, constructed
using the private payment data needed to establish the right to resolve the
hold. Neither party needs to supply a new spending-key signature. The input
notes remain unspent and under the same spending key. For both acceptance and rejection, the
recipient VASP is responsible for its decision. [Privacy-Preserving
Policy](https://docs.metalntwx.com/learn/mip410/privacy-preserving-policy.md) explains how the policy-wrapper
proof is tied to that decision.

### Reclaim

```text theme={null}
Any submitter
  -> submits a reclaim transaction for an expired, unresolved hold
MIP410 shielded pool
  -> checks that the hold is unresolved and its deadline has passed
  -> marks the hold as reclaimed and releases the input locks
```

Expiry does not release the locks automatically. It requires a reclaim transaction.
Reclaim needs no spending authorization, viewing key, or proof. Any
EVM account can submit it. The notes remain under the original spending key.
It does not transfer them to the submitter.

### Unshielding

```text theme={null}
Customer
  -> asks the VASP to turn shielded notes into public MIP20 value
VASP
  -> prepares the input notes, public destination, amount, and any change note
Customer's wallet or custodian
  -> signs the unshield authorization with the spending key
Proving service
  -> builds the unshield proof using the signed authorization
Submitter
  -> submits the unshielding transaction and proof
MIP410 shielded pool
  -> verifies the proof and checks that the input notes are unlocked and unspent
  -> spends the input notes, records any change note, and transfers the MIP20 value
```

The signature fixes the token, amount, destination, input notes, and any
change note. It also binds the transaction to the chain ID, pool contract
address, and state used by the proof. The note updates and public transfer
succeed or revert together.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.