Memo Block

The main transaction part containing the encrypted data to restore balances and history

Memo overview

The memo block contains detailed transaction data such as output notes, accounts, transaction fee, and other specific fields. It consist of 3 subblocks: transaction specific, message and extra data which are explained below

Common memo block structure

Memo Block Versioning

The current page contains universal memo block structure which is used in calldata format V2. In this version we introduced symmetric scheme for shared secrets encryption and separeted fees for proxy and prover.

The first version of memo block wasn't designed to support decentralized relayer so the field structure is different. Moreover the shared secret encryption was based on the ECDH scheme. To find associated fields length please refer to the transaction calldata V1

Transaction Specific

The subblock length and constitution depends on transaction type and contains fields needed to display transaction correctly by a client. There are three fixed fields applicable for every transaction type (proxy, proxy fee and prover fee). Permit deposit and withdrawal transactions have additional fields.

Approve Deposit \ Transfer

The block depends on transaction type

Field name	Size (bytes)	Description
proxy	20	L1 address of proxy who can commit this transaction on the pool contract.
prover	20	L1 address of the primary prover who can finalize this transaction during the grace period (after which anyone can finalize it)
proxy fee	8	Asset amount designated to the proxy for commitment publishing
prover fee	8	Asset amount designated to the prover who will finalize transaction commitment by tree proving and publishing new Merkle root

Total bytes: 56

Withdrawal

Permit Deposit

Obsolete Memo Differences

Previously we used an old version of the memo block without proxy, prover, proxy fee and prover fee fields (since the centralised relayer model was used). Instead there was a single field fee - asset amount designated to the relayer node. You can look for the old memo block in calldata V1 reference page

Transaction Message

The transaction message is the main part of the memo used to synchronize local Merkle tree by a client. It contains encrypted parts of the transaction and needed during the client Merkle tree synchronization. In some cases message can be un-encrypted (e.g. direct deposit). The client app will try to decrypt every message to find transactions associated with his account.

The length of the message is explicitly defined in the memo block with $MsgSize$ field. The content of the message (without length) is emitted by the pool contract in the Message event on transaction commitment. The message content are fully defined by the client side. In the current implementation we use symmetric encryption format for encrypted message. In the previous calldata version (V1) ECDH encryption was used.

Transaction Message Understanding

Transaction message exists not only in the context of memo block. For regular transactions (transact or transactV2 methods) it's a part of memo block and content of emitted Message events. For direct deposit transactions it's a content of emitted Message events which produced by appendDirectDeposits method.

Symmetric

Field name	Size (bytes)	Description
$MsgSize$	2	Size of the following transaction message in bytes (this field is not included)
$ItemsNum$	2	Number of encrypted elements in the memo block. An element is an account or a note. Note has a fixed number of items currently: one output account and 127 notes.
$EncType$	2	0x0000: ECDH encryption mode 0x0001: plain text (used for direct deposits) 0x0002: symmetric encryption mode
$Hash_{account}(acc)$	32	Output account hash (with updated balance).
$Hash_{note}(Note_i)$	32	Output note hash.
$nonce$	24	XChaCha20 nonce. Used to decrypt $Keys^\text{enc}$by transaction sender.
$Keys^\text{enc}$	32 * $ItemsNum$ + 16	Encrypted keys to decrypt output account and notes. Only the transaction sender can decrypt these keys.
$acc^\text{enc}$	86	Encrypted output account with an updated balance.
$A_i$	32	Ephemeral public key for notes. Used to decrypt $Note_i^\text{enc}$ by note owner (receiver).
$Note_i^\text{enc}$	76	Encrypted note. It can be decrypted with $A_i$ by owner or by transaction sender through a $Keys^\text{enc}$ disclosure.

Plain

ECDH (obsolete)

Extra Data

The remaining part of the memo block contains extra_data which consist of arbitrary user data (e.g. a text comment for transaction). The extra_data field doesn't processed by smart contract. It's fully defined by the client side and doesn't described here.