discover self-custodial docs

[Trivo25]

• go through the docs of the parent issue
• get an understanding of the project

[Shigoto-dev19]

To understand the project design and requirements, start by reviewing the Notion documentation hub: Treasury - Notion.

This hub links to multiple supporting pages that describe the requirements, architecture, and UI design. The primary pages to review are:

• Requirements — Self Custody Treasury

• zkApp Architecture

• UI Specification

• Along with the codebase: https://github.com/o1-labs-XT/multisig-zkapp

[Shigoto-dev19]

The original specification defines both v1 and v2; this report and implementation cover v1 only

Project Requirements Summary

The core project requirements can be summarized as follows:

• Hold 100k MINA in a single multisig zkApp account
• Require 2 out of 4 multisig approvals to authorize transfers
• Support single-key authority to approve delegation to a single block producer

For full details, refer to: Requirements — Self Custody Treasury Notion page.

Notes on Specification vs Implementation

The Notion specification is largely aligned with the implemented codebase, with two important differences:

• Withdrawals are not restricted to a hardcoded whitelist
  The current implementation does not enforce a fixed withdrawal whitelist, even though this is mentioned in the requirements document (see the related note in the Requirements page).

• Replay protection uses a flexible nonce rule
  Instead of requiring a strictly sequential nonce, the implementation accepts any transfer command whose nonce is greater than the nonce currently stored on-chain. This provides more flexibility than a strictly incremental nonce model.

[Shigoto-dev19]

This report summarizes the project architecture based on the codebase and available documentation.

See the ZkApp Architecture notion page and the codebase for more details.

ZkApp Architecture

Overview

The MultiSigZkApp implements a 2-of-4 multi-signature scheme to manage a shared treasury where transfers require approval from any 2 of 4 authorized signers, and stake delegation is controlled by a separate dedicated authority.

At a high level, the contract lifecycle works as follows:

1. Deployment: The zkApp is deployed, setting strict permissions.
2. Initialization: A separate initialize method is called (once) with the public keys of the 4 authorized signers and the delegation authority. Their Poseidon hashes are stored on-chain.
3. Transfers: Any 2 of the 4 signers sign the same transfer details (recipient, amount, nonce), and the transaction is submitted with both signatures. The contract verifies both signatures, checks signer authorization and distinctness, then executes the transfer.
4. Stake Delegation: A separate single-signer flow; the delegation authority signs the new validator's public key, and the contract updates the stake delegate accordingly.

For more details, read the description from this slack message.

On-Chain States

The contract uses 6 out of 8 available state fields:

State Field	Type	Purpose
signerHash0	Field	Poseidon hash of signer 0's public key
signerHash1	Field	Poseidon hash of signer 1's public key
signerHash2	Field	Poseidon hash of signer 2's public key
signerHash3	Field	Poseidon hash of signer 3's public key
nonce	Field	Replay protection counter
delegationAuthorityHash	Field	Poseidon hash of the delegation authority

Permissions

The contract sets strict permissions at deployment via init():

Permission	Value	Effect
editState	proof()	State changes require valid proof
send	proof()	Outgoing transfers require valid proof
receive	none()	Anyone can send MINA to the contract
setDelegate	proof()	Delegation changes require valid proof
setVerificationKey	impossibleDuringCurrentVersion()	No contract upgrades without a hardfork
setPermissions	impossible()	Permissions are immutable
setZkappUri	impossible()	Immutable
setTokenSymbol	impossible()	Immutable
setTiming	impossible()	Immutable

Initialization Method (initialize)

Once a MultiSigZkApp is deployed, it must be initialized through the initialize method, which takes:

• 4 signer public keys (signer0 through signer3)
• 1 delegation authority public key

The method enforces the following:

1. One-time only: Checks that signerHash0 == 0 (default), rejecting subsequent calls.
2. All 4 signers must be distinct — all 6 pairwise equality checks are performed.
3. Delegation authority must differ from all 4 signers — 4 equality checks against signer hashes.
4. Each public key is Poseidon-hashed and stored in its respective state field.
5. Nonce is initialized to 0.
6. An initialized event is emitted containing Poseidon.hash([hash0, hash1, hash2, hash3, delegationHash]).

Note: No other method can update the signers or delegation authority after initialization. The set of authorized keys is permanently fixed at initialization time.

Note: There's no restriction on who can call the initialize method.

Transfer Method (transfer)

The primary operation; sending funds from the treasury.

Inputs

Parameter	Type	Description
command	TransferCommand	Struct containing recipient, amount, and nonce
signer1	PublicKey	First approving signer's public key
sig1	Signature	First signer's signature over command fields
signer2	PublicKey	Second approving signer's public key
sig2	Signature	Second signer's signature over command fields

Validation & Execution Steps

1. Nonce check: command.nonce must be strictly greater than the current on-chain nonce (replay protection + out-of-order support).
2. Signature verification: sig1 is verified against signer1 over command.toFields(), and sig2 against signer2 over the same fields.
   • This ensures both signers agree on the exact same recipient, amount, and nonce.
3. Signer authorization: Both signer1 and signer2 are checked for membership in the stored signer hashes.
4. Signer distinctness: signer1 ≠ signer2 is asserted.
5. Funds transfer: this.send({ to: command.recipient, amount: command.amount }).
6. Event emission: A transferExecuted event is emitted containing { recipient, amount, nonce, signer1, signer2 }.
7. Nonce update: On-chain nonce is set to command.nonce (not incremented by 1).

Note: There is no restriction on who calls the transfer method — any account can submit the transaction, as long as the proof contains valid signatures from 2 authorized signers.

Note: There's no restriction on the amount or recipient of the transfer.

Note: Both signers must sign the identical TransferCommand and coordinate off-chain (e.g. via the UI).

Nonce Semantics

The nonce design supports more than simple sequential replay protection:

• Gaps are allowed: Executing nonce 5 after nonce 1 is valid — the on-chain nonce jumps to 5.
• Implicit cancellation: If a command with nonce 3 is pending but a command with nonce 5 executes first, the nonce-3 command becomes permanently invalid.
• Out-of-order execution: Higher-nonce commands can execute before lower-nonce ones, as long as the nonce is greater than the current on-chain value.

See Replay Attack Prevention Notion page for more details. Note that the approach implemented in code is a flexible nonce-based approach (command.nonce > currentNonce) rather than a strict sequential nonce (command.nonce == currentNonce + 1).

Stake Delegation Method (delegateStake)

Allows delegating the contract's staking rights to a validator, controlled by a separate, dedicated authority key — not the transfer signers.

Inputs

Parameter	Type	Description
newDelegate	PublicKey	Public key of the validator to delegate to
authority	PublicKey	Delegation authority's public key
sig	Signature	Authority's signature over [newDelegate ‖ zkAppAddress]

Validation & Execution Steps

1. Authority verification: Hashes the provided authority and asserts it matches the stored delegationAuthorityHash.
2. Signature verification: Verifies sig against authority over the message [...newDelegate.toFields(), ...this.address.toFields()].
   • Including the zkAppAddress in the signed message binds the delegation intent to this specific contract.
3. Delegation set: this.account.delegate.set(newDelegate).
4. Event emission: A delegationChanged event is emitted containing { newDelegate, initiatedBy: authority }.

Note: Delegation is single-signer (1-of-1), unlike transfers which require 2-of-4.

Utility Methods

Method	Purpose
verifySigner	Verifies a single public key is an authorized signer (on-chain)
verifySigners	Verifies 2 public keys are both authorized signers and distinct

These are callable on-chain methods that can be used for external verification.

Events Summary

Event	Emitted By	Payload
initialized	initialize()	Poseidon.hash([signerHash0, signerHash1, signerHash2, signerHash3, delegationHash])
transferExecuted	transfer()	{ recipient, amount, nonce, signer1, signer2 }
delegationChanged	delegateStake()	{ newDelegate, initiatedBy }

Privacy

There is no specific privacy requirement for this zkApp, but this section summarizes what information is and isn't exposed on-chain.

On-chain state stores only Poseidon hashes of all public keys (signers and delegation authority) — the actual keys are never stored in plaintext.

Method inputs in zkApps are private witnesses to the proof and are not included in on-chain transaction data. The methods themselves do not expose the signer or authority public keys.

Events, however, do reveal certain keys:

Method	Keys Exposed in Events
initialize	None (only aggregate hash)
transfer	Both signer public keys
delegateStake	Delegation authority key
Utility methods	None

verifySigner / verifySigners methods makes it possible for observers to infer contextual information from transaction patterns and senders, but not from state storage alone.

[Shigoto-dev19]

UI & Backend Specifications

To understand the intended product behavior and overall system design, refer to the following two primary resources:

• UI Spec Notion page — Main
• Backend Spec Notion page

UI Spec Summary

The UI Spec describes the dashboard structure and user experience, including:

• screen layouts and navigation flow,
• signer and operator interactions across screens,
• command creation, signing, execution, and history views,
• account and delegation management flows.

Notes

• There is no hardcoded whitelist in the zkApp, but the UI shows a dropdown list with Coinbase and Kraken as selectable recipients.

• The project requirements mention using emitted events for accounting:

  • Will there be a dedicated page, and will accounting be added to the allowlist?
  • Or, is it intended to share information from the transaction history?
  • Overall, it would be useful to see how events are used in the UI in order to better understand the zkApp event fields.

• The UI Spec and Backend Spec do not mention how the nonce is incremented, how often it's fetched from the zkApp, or by how much it's incremented.

  • Does it increment considering all pending transfer commands as well?
  • Does use the nonce on purpose for implicit cancellation?

Backend Spec Summary

The Backend Spec defines the supporting services and APIs, including:

• transfer command CRUD operations,
• signature collection and storage,
• execution of zkApp calls once signature thresholds are met,
• the microservice structure used to support these operations.