Protocol

The lock

The Winternitz one-time signature over SHA-256: keys, commitment, signing, verification, the checksum.

The lock is a Winternitz one-time signature over SHA-256, implemented in hashlock.rs. Write $H$ for SHA-256 and $H^{k}$ for $k$ applications of it:

H^{0}(x) = x, \qquad H^{k}(x) = H\!\left(H^{k-1}(x)\right).

Parameters

Name	Value	In the source
Winternitz parameter $w$	256	`WINTERNITZ_W`
Message chains $\ell_1$	32	`MESSAGE_CHAINS`
Checksum chains $\ell_2$	2	`CHECKSUM_CHAINS`
Total chains $\ell$	34	`TOTAL_CHAINS`
Chain length $w - 1$	255	`CHAIN_LENGTH`
Signature size	34 × 32 = 1,088 bytes	`SIGNATURE_BYTES`
Commitment size	32 bytes	`Vault.commitment`
Chains per push	8	`CHAINS_PER_PUSH`

$w = 256$ means one chain per byte of a 32-byte digest. The choice is forced by Solana’s 1,232-byte transaction limit, not by cryptography. A Lamport signature over 256 bits is 256 × 32 = 8,192 bytes. At $w = 16$ there are 64 message chains and 3 checksum chains, 2,144 bytes, still too large. At $w = 256$ the signature is 1,088 bytes and fits, with the verification spread over several transactions.

Keys and the commitment

A private key is 34 random 32-byte values, one per chain, derived off chain from the seed. The public key is each value hashed 255 times.

\mathit{sk} = (x_1, \ldots, x_{34}), \qquad x_i \in \{0,1\}^{256}

\mathit{pk}_i = H^{255}(x_i), \qquad i = 1, \ldots, 34

The vault does not store the 1,088-byte public key. It stores one hash of it, under a domain tag, so a vault costs 32 bytes rather than 1,088. This is the commitment.

C = H\!\left(\texttt{metaspace:commitment:v1} \,\|\, \mathit{pk}_1 \,\|\, \cdots \,\|\, \mathit{pk}_{34}\right)

The tag is the 23-byte ASCII string.

\|

is concatenation. Computed by commitment_of.

Commitment preimage, 23 + 34 × 32 = 1,111 bytes

"metaspace:commitment:v1" || pk[0] || pk[1] || ... || pk[33]
commitment = SHA-256(preimage)

Encoding a digest

The thing signed is a 32-byte digest $d = (d_1, \ldots, d_{32})$ , one byte per message chain. The first 32 chain lengths are the bytes themselves.

m_i = d_i, \qquad 0 \le m_i \le 255, \qquad i = 1, \ldots, 32

The checksum is a plain subtraction, so the argument below can be checked by eye.

c = 32 \cdot 255 - \sum_{i=1}^{32} m_i = 8160 - \sum_{i=1}^{32} m_i

c

ranges from 0 to 8,160. Computed by chain_steps.

It is split big-endian across the two checksum chains.

m_{33} = \left\lfloor c / 256 \right\rfloor, \qquad m_{34} = c \bmod 256

Since 8160 = 31 · 256 + 224,

m_{33}

never exceeds 31.

Signing

To sign, release each chain value hashed $m_i$ times. A byte of 0 releases the private value itself. A byte of 255 releases the public value, which reveals nothing further.

\sigma_i = H^{m_i}(x_i), \qquad \sigma = (\sigma_1, \ldots, \sigma_{34})

The signature is 34 values of 32 bytes, 1,088 bytes. Signing costs $\sum_i m_i$ hashes.

Verification

The verifier recomputes the chain lengths from the digest, walks each released value the remaining distance to its endpoint, and hashes the endpoints together.

e_i = H^{255 - m_i}(\sigma_i), \qquad i = 1, \ldots, 34

\text{accept} \iff H\!\left(\texttt{metaspace:commitment:v1} \,\|\, e_1 \,\|\, \cdots \,\|\, e_{34}\right) = C

Compared against Vault.commitment in finalize_withdrawal.

A genuine signature verifies because hashing composes:

H^{255 - m_i}\!\left(H^{m_i}(x_i)\right) = H^{255}(x_i) = \mathit{pk}_i.

Verification costs $\sum_i (255 - m_i)$ hashes. Signer and verifier together always do exactly $34 \cdot 255 = 8670$ . For a uniformly random digest the verifier’s share is about 4,300. Solana’s compute limit is 1.4 million units per transaction, which is why the verifier’s walk is split across several transactions. One push of 8 chains is at most $8 \cdot 255 = 2040$ hashes.

Why the checksum stops forgery

An attacker holds a valid signature $\sigma$ on $m$ and wants a signature on some other digest $m'$ . For a single chain, moving forward is free and moving backward is not:

m'_i \ge m_i: \quad \sigma'_i = H^{\,m'_i - m_i}(\sigma_i) \quad\text{(computable)}

m'_i < m_i: \quad \sigma'_i \text{ is a preimage of } \sigma_i \text{ under } H^{\,m_i - m'_i} \quad\text{(inverting SHA-256)}

So a forgery is only cheap if every chain moves forward or stays. Suppose the message chains all satisfy $m'_i \ge m_i$ and at least one is strictly larger. Then the sum rises, so the checksum falls:

\sum_{i=1}^{32} m'_i > \sum_{i=1}^{32} m_i \;\Longrightarrow\; c' < c.

Because $c$ is split big-endian, $c' < c$ means either $m'_{33} < m_{33}$ , or $m'_{33} = m_{33}$ and $m'_{34} < m_{34}$ . Either way a checksum chain must move backward. There is no $m' \ne m$ in which every one of the 34 chains moves forward or stays still. Every forgery is therefore a preimage of SHA-256, which is the $2^{128}$ search in Threat model.

This is the entire argument, and it is why the checksum chains are not optional.

The digest and what it binds

The digest is not chosen freely. It is the hash of the withdrawal request, as written on chain before any chain value is revealed. Everything that could be substituted is in it.

d = H\!\left(\texttt{metaspace:withdraw:v1} \,\|\, \mathit{vault} \,\|\, \mathit{nonce} \,\|\, \mathit{amount} \,\|\, \mathit{dest} \,\|\, C_{\mathrm{next}}\right)

Computed by WithdrawalRequest::digest. Integers are little-endian 64-bit.

Digest preimage, 133 bytes

"metaspace:withdraw:v1"   // 21 bytes, ASCII
|| vault                   // 32 bytes, the vault's address
|| nonce                   //  8 bytes, u64 little-endian
|| amount                  //  8 bytes, u64 little-endian, lamports
|| destination             // 32 bytes
|| next_commitment         // 32 bytes
digest = SHA-256(preimage)

Field	Bytes	What it stops
metaspace:withdraw:v1	21	A signature for one message format being read as another.
vault	32	Replaying a signature against a different vault.
nonce	8	Replaying a signature against a later state of the same vault.
amount	8	Changing how much is paid.
destination	32	Changing who is paid. The finaliser cannot choose this.
next_commitment	32	Substituting the lock the vault rotates to.

What is absent on purpose: the submitter. Binding the finaliser’s key would mean only one party could land the withdrawal. That turns a failed transaction into a stuck vault and buys nothing, because the destination is already fixed.