Viewing Keys & Selective Disclosure
How wallet viewing keys and single-transaction Transaction Viewing Keys (TVKs) prove settled fills without exposing wallet history.
Confidential trading requires selective disclosure: a trader or desk must be able to prove one settled execution to an auditor, accountant, or counterparty without revealing unrelated balances or other trades. Mera separates this into a Ring-scoped wallet viewing key fingerprint and per-trade Transaction Viewing Keys (TVKs).
Two levels of disclosure
| Key type | Scope | Where it appears | What it reveals |
|---|---|---|---|
| Wallet viewing key | One wallet in one Ring (viewingKeyFingerprint) | /balance and GET /v1/balances/:wallet | Unspent CommitmentNote list and decrypted shielded balances for that wallet in that Ring |
| Transaction Viewing Key (TVK) | One single settled trade | /trade fills table, POST /v1/transactions/submit, GET /v1/fills | Exact pair, mode, side, input amount, output amount, execution price, fee, slot, finality ms, commitment hash, nullifier hash, and transaction signature for that trade alone |
Sharing a TVK reveals nothing about the trader's remaining shielded balance, other open hidden orders, or other fills in the same Ring.
TVK format and payload structure
A Mera v1 TVK is a base64-encoded JSON payload prefixed with mera_tvk_v1_:
mera_tvk_v1_<base64(UTF-8 JSON payload)>The decoded TvkPayload contains 17 fields:
| Field | Type | Description |
|---|---|---|
v | 1 | TVK schema version |
settlementId | string | Unique settlement identifier (e.g. stl_...) |
ringId | string | Ring identifier where the fill cleared |
pairId | string | Trading pair (e.g. SOL-USDC) |
mode | string | swap, hidden-order, or sealed-rfq |
side | string | buy or sell |
inputAmount | string | Exact input amount in base units (u64 string) |
outputAmount | string | Exact net output amount in base units (u64 string) |
executionPrice | number | Settled execution price |
feeAmount | string | Exact protocol fee paid in base units (u64 string) |
feeBps | number | Protocol fee rate in basis points at settlement |
commitmentHash | string | 32-byte hex SHA-256 settlement commitment hash |
nullifierHash | string | 32-byte hex taker input nullifier hash |
slot | number | Solana slot in which the trade confirmed |
finalityMs | number | Measured confirmation latency in milliseconds |
signature | string | Base58 Solana transaction signature |
settledAt | string | ISO-8601 UTC timestamp |
Cryptographic verification
When a TVK is submitted to /receipts or POST /v1/receipts/verify, the verifier executes three checks:
- Format check. Confirms the
mera_tvk_v1_prefix, valid base64 JSON,v === 1, and required string fields. Malformed input returnsINVALID_TVK(400). - Commitment hash check. Recomputes the domain-separated SHA-256 settlement commitment hash from the disclosed fields:
recomputed = SHA-256(
"mera:settlement:v1:" || settlementId || ":" || ringId || ":" || pairId ||
":" || inputAmount || ":" || outputAmount || ":" || feeAmount
)If recomputed !== payload.commitmentHash, any field was altered after settlement and the verifier rejects the key with INVALID_TVK (400).
- On-chain record check. Looks up the
RfqSettlementRecordPDA (["settlement", ring_pubkey, SHA-256(settlementId)]) on Solana RPC viagetAccountInfoand confirms the account exists and is owned bymera_core(3w9NcCZK118PzMLmfbS5si5Q5hpA3DMEuYyfVo5fkE1B). The result is returned inonchainMatched: boolean.
The first 16 bytes of commitmentHash are also stored on chain in RfqSettlementRecord.tvk_hint and emitted in the SettlementCleared event so indexers and auditors can match TVKs to on-chain records without scanning plaintext amounts.