Build on
Ghost Protocol
A non-existence primitive for developers. Build applications where sensitive data is never stored, only proven.
Architecture Overview
Four core contracts power the Ghost Protocol system.
GhostVault
Holds committed value, releases on valid reveal
GhostCommitmentTree
Merkle tree storing commitment hashes
GhostNullifierRegistry
Prevents double-reveals with nullifier tracking
GhostRedemptionVerifier
zk-SNARK proof verification
Core Concepts
The developer mental model for building with Ghost Protocol.
Commitment
Cryptographic hash proving data exists without revealing it
Reveal
One-time action that proves knowledge of the secret
Nullifier
Unique marker preventing double-spends
Network Configuration
Add to MetaMask or any EVM wallet to start building.
Contract Addresses
Deployed contracts on Umbraline Testnet. Click to copy or view on explorer.
GhostVault
Main entry point for commits and reveals
CommitmentTree
Merkle tree storing commitment hashes
NullifierRegistry
Tracks spent nullifiers to prevent double-reveals
ProofVerifier
MOCKzk-SNARK proof verification (mock for testnet)
GhostERC20Factory
Factory for creating privacy-enabled ERC20 tokens
Cryptographic Constants
Essential values for building with Ghost Protocol cryptography.
FIELD_SIZE (BN254 (alt_bn128))
All values in proofs must be less than this number
21888242871839275222246405745257275088548364400416034343698204186575808495617Commitment Formula
Creates a binding commitment to your data
commitment = Poseidon(secret, dataHash)Nullifier Formula
Derives a unique identifier for reveals
nullifier = Poseidon(secret, 1)Code Examples
Essential patterns for building with Ghost Protocol. See full documentation
import { poseidon2 } from 'poseidon-lite';
// Hash two field elements
const hash = poseidon2([input1, input2]);
// The result is a BigInt < FIELD_SIZE
console.log(hash.toString());Contract ABIs
Function signatures for interacting with Ghost Protocol contracts.
Error Codes
Common errors and how to resolve them.
| Error | Description |
|---|---|
InvalidProof | The zk-SNARK proof failed verification |
NullifierAlreadySpent | This nullifier has already been used |
UnknownRoot | The Merkle root is not recognized |
InvalidCommitment | Commitment value is outside field size |
TreeFull | The commitment tree has reached capacity |
CallbackFailed | Application callback reverted |
Gas Estimates
Approximate gas costs for common operations.
| Function | Gas Range | Notes |
|---|---|---|
commit() | 75K - 100K | Base commitment to tree |
verifyAndNullify() | 150K - 200K | Includes proof verification |
commitWithCallback() | 100K - 150K | With application callback |
revealWithCallback() | 200K - 300K | Full reveal flow with callback |
Quick Commands
Foundry cast commands for interacting with Ghost Protocol.
Check Block Number
Get the current block number
cast block-number --rpc-url https://testnet-rpc.umbraline.comGet Commitment Count
Total commitments in the tree
cast call 0xe382a7C7a5CE3B9250D73aE6ab97931E5798e6F7 "leafCount()(uint256)" --rpc-url https://testnet-rpc.umbraline.comCheck Nullifier Status
Check if a nullifier has been spent
cast call 0x03972E4453fD143A5203602020DbE2f7DcF6e0db "isSpent(bytes32)(bool)" <nullifier> --rpc-url https://testnet-rpc.umbraline.comGet Current Root
Get the current Merkle root
cast call 0xe382a7C7a5CE3B9250D73aE6ab97931E5798e6F7 "currentRoot()(bytes32)" --rpc-url https://testnet-rpc.umbraline.comSafety Rules
Critical guidelines for working with Ghost Protocol.
DataHash Binding
Your dataHash encodes ALL value and terms. Once committed, the dataHash cannot be changed. Verify all parameters before committing.
No Secret Recovery
Lost secrets = lost commitment forever. There is no recovery mechanism. Always securely backup your secrets before committing.
Nullifier is Final
Once a nullifier is revealed, that commitment can never be used again. The reveal action is irreversible.
Root Freshness
Merkle roots expire after approximately 100 tree updates. Generate proofs close to submission time.
Field Size Constraint
All values must be less than FIELD_SIZE. Values exceeding this will cause proof generation to fail.