Skip to main content

Privacy Module

The Privacy module enables optional zkSNARK-based shielded transactions on RP1.

Overview​

FeatureDescription
Proving SystemGroth16 on BN254
Hash FunctionMiMC (ZK-friendly)
Anonymity Set11 (1 real + 10 decoys)
Proof Size256 bytes
Verify Time~2ms

Operations​

Shield Tokens​

Convert public tokens to private:

rp1d tx privacy shield 1000000urp1 \
  --from my-wallet \
  --chain-id rp1-1
import { PrivacyModule } from '@rp1/sdk';

const privacy = new PrivacyModule(client);
const tx = await privacy.shield(wallet, '1000000', 'urp1');

Private Transfer​

Transfer privately with ring signatures:

rp1d tx privacy transfer \
  --recipient rp1recipient... \
  --amount 500000urp1 \
  --from my-wallet
const tx = await privacy.transfer(wallet, 'rp1recipient...', '500000');

Unshield Tokens​

Convert private tokens back to public:

rp1d tx privacy unshield 500000urp1 \
  --from my-wallet
const tx = await privacy.unshield(wallet, '500000', 'urp1');

Viewing Keys​

Grant auditors access to view your transactions:

Create Viewing Key​

rp1d tx privacy create-viewing-key \
  --grantee rp1auditor... \
  --type full \
  --expiry "2025-12-31T00:00:00Z" \
  --from my-wallet

Viewing Key Types​

TypeCan See
fullAll transactions and balances
incomingOnly incoming transactions
outgoingOnly outgoing transactions
balanceCurrent balance only

Revoke Viewing Key​

rp1d tx privacy revoke-viewing-key \
  --grantee rp1auditor... \
  --from my-wallet

Query Commands​

Get Shielded Balance​

# With your spending key
rp1d query privacy balance --from my-wallet

List Viewing Keys​

rp1d query privacy viewing-keys $(rp1d keys show my-wallet -a)

Pool Statistics​

rp1d query privacy pool-stats

Message Types​

MsgShield​

message MsgShield {
  string sender = 1;
  cosmos.base.v1beta1.Coin amount = 2;
}

MsgPrivateTransfer​

message MsgPrivateTransfer {
  string sender = 1;
  string recipient = 2;
  bytes proof = 3;
  bytes encrypted_amount = 4;
  repeated bytes ring_members = 5;
}

MsgUnshield​

message MsgUnshield {
  string sender = 1;
  cosmos.base.v1beta1.Coin amount = 2;
  bytes proof = 3;
  bytes nullifier = 4;
}

Parameters​

ParameterDefaultDescription
ring_size11Number of decoys + 1
min_shield_amount1000Minimum shield amount
max_viewing_key_duration365 daysMax viewing key validity
proof_verification_gas200000Gas for proof verification

Events​

// Emitted on shield
EventTypeShield = "privacy_shield"
AttributeKeyAmount = "amount"
AttributeKeyCommitment = "commitment"

// Emitted on transfer
EventTypePrivateTransfer = "privacy_transfer"
AttributeKeyNullifier = "nullifier"

// Emitted on unshield
EventTypeUnshield = "privacy_unshield"
AttributeKeyRecipient = "recipient"

Security Considerations​

  1. Note Storage: Keep your spending key secure - it's required to spend shielded tokens
  2. Viewing Keys: Only grant to trusted parties; revoke when no longer needed
  3. Timing: Avoid shielding immediately before spending for better anonymity
  4. Amount Patterns: Use standard amounts to improve mixing
  5. Decoy Selection: Let notes age for better anonymity set

Gas Costs​

OperationGasApproximate Cost
Shield200,000~$0.0002
Transfer350,000~$0.00035
Unshield200,000~$0.0002
Create Viewing Key50,000~$0.00005

Next Steps​