DOCSEARCHbyAlgolia
Submit Docs

Penumbra Documentation

repository·main·Indexed 19 days ago

https://github.com/penumbra-zone/penumbra

A shielded zone for the Cosmos ecosystem enabling secure transactions, staking, swapping, and market making without broadcasting personal information. This repository includes the node implementation (pd), the command line client (pcli), the pindexer tool for processing ABCI events, and the penumbra-tct crate for Tiered Commitment Tree implementation.

Tokens
174.7K
Snippets
493
Records
852
Agent score
66%

What's inside Penumbra

  1. Overview of Penumbra cryptographic primitives

    main

    Penumbra's protocol is built upon several specialized cryptographic constructions designed for privacy, zero-knowledge proofs, and efficient transaction processing. Key primitives include:

    • Proof Systems: Uses the BLS12-377 proving curve with the Groth16 proof system (with potential future support for PLONK).
    • Decaf377: A parameterization of the Decaf construction over the BLS12-377 scalar field, providing a prime-order group suitable for use both inside and outside of circuits.
    • Poseidon for BLS12-377: A SNARK-friendly sponge construction (Poseidon) instantiated over the BLS12-377 scalar field.
    • Fuzzy Message Detection (FMD): A construction for outsourcing probabilistic detection, allowing third parties to scan and filter the chain without revealing specific transaction identities.
    • Homomorphic Threshold Decryption: Used to enable the batching of flows of value across transactions.
    • decaf377-rdsa: A variant of the Zcash RedDSA construction instantiated over decaf377, used for binding and spend authorization signatures.
    • decaf377-ka: An instantiation of Diffie-Hellman key agreement over decaf377.

  2. Overview of pindexer

    main

    pindexer

    pindexer is a tool that processes blockchain data by reading from a raw data database and writing to a compiled data database.

    Core Requirements:

    • Raw Data Database: Contains raw data from CometBFT.
    • Compiled Data Database: Contains data translated into schemas determined by pindexer.
    • ABCI Events Database: A local database of ABCI events must be present. The recommended way to set this up is by following the Penumbra Guide for devnet instructions.

  3. Overview of Penumbra Protocol

    main

    Penumbra is a fully private proof-of-stake network and decentralized exchange (DEX) designed for the Cosmos ecosystem. It integrates privacy with proof-of-stake using a novel private delegation mechanism. Key features include:

    • Private Transactions: Uses a multi-asset shielded pool based on the Zcash Sapling design, supporting any IBC-compatible asset.
    • Private Staking: Uses delegation tokens (staking derivatives) to enable private staking and fungible delegations.
    • Private Governance: Supports on-chain governance with secret ballots and anonymous proposals.
    • Private DEX (ZSwap): A decentralized exchange supporting sealed-bid batch auctions and anonymous concentrated liquidity positions.

  5. Access Penumbra documentation and resources

    main

    Penumbra provides several specialized documentation portals depending on your needs:

  6. Available Community Pool Transaction Actions

    main

    The Community Pool component supports three primary transaction actions for interacting with the pool's governance and liquidity:

    1. Deposit: Use core.component.governance.v1.CommunityPoolDeposit to add assets to the community pool.
    2. Output: Use core.component.governance.v1.CommunityPoolOutput to manage or distribute outputs from the pool.
    3. Spend: Use core.component.governance.v1.CommunityPoolSpend to execute spending logic related to the pool.

  7. Available DEX Transaction Actions

    main

    The Penumbra decentralized exchange (DEX) component supports several specific transaction actions for trading, liquidity management, and reward collection. These actions are defined under the core.component.dex.v1 namespace.

    Available actions include:

    • Swap: Execute a token swap.
    • SwapClaim: Claim the results of a swap.
    • PositionOpen: Open a new liquidity position.
    • PositionClose: Close an existing liquidity position.
    • PositionWithdraw: Withdraw assets from a liquidity position.
    • PositionRewardClaim: Claim earned rewards from a liquidity position.

  8. Explore Penumbra deployment assets

    main

    The deployments/ directory contains various assets for node operators and developers:

    • systemd/: Example systemd configuration files for running Penumbra nodes as services.
    • containerfiles/: OCI container image manifests for building containerized versions of Penumbra.
    • scripts/: Scripts used for testing Penumbra within CI environments.
    • compose/: Example docker-compose configurations (Note: this directory is currently unmaintained).
    .
├── systemd/           # example systemd configs for node operators
├── containerfiles/    # OCI container image manifests
├── scripts/           # scripts related to testing penumbra in ci
├── containerfiles/    # OCI container image manifests
└── compose/           # example docker-compose configs, unmaintained

  9. Available Governance Transaction Actions

    main

    The Penumbra governance component supports several specific transaction actions for managing validator votes, delegator votes, and proposal lifecycles. These actions are defined under the core.component.governance.v1 namespace.

    - `core.component.governance.v1.ValidatorVote`
- `core.component.governance.v1.DelegatorVote`
- `core.component.governance.v1.ProposalSubmit`
- `core.component.governance.v1.ProposalWithdraw`
- `core.component.governance.v1.ProposalDepositClaim`

  10. Understand the status of Flow Encryption in Penumbra

    main

    Flow Encryption is a mechanism designed to achieve privacy in multi-party contexts where knowledge from multiple participants is required.

    Important Note: Flow Encryption will not ship in Penumbra V1 due to delays in ABCI 2.0. Consequently, flow contributions will remain in the clear (unencrypted) until a future network upgrade. The current documentation for these features is a work-in-progress and may not reflect the current protocol state.

  12. What is the Tiered Commitment Tree (TCT)?

    main

    The Tiered Commitment Tree (TCT) is the data structure used by the Penumbra protocol's State Commitment Tree (SCT) to store cryptographic commitments to shielded state (such as note and swap commitments). It is an append-only, ZK-friendly Merkle tree designed to balance proof depth and proof size using the Poseidon hash.

    Key characteristics include:

    • Quaternary Structure: Each node has four children. This results in a shallower tree compared to binary trees, reducing the number of hash operations required for insertions while keeping proofs smaller than an octal tree.
    • Sparse: Clients can maintain a version of the tree that only represents commitments pertinent to their specific state. Unrelated commitments and their internal hashes are pruned to a single summary hash.
    • Semi-Lazy: Internal hashes along the tree's frontier are computed on demand (only when providing an inclusion proof or computing the root hash), providing an amortized 12x performance boost during scanning.
    • Tiered Hierarchy: The structure is a triply-nested tree-of-trees-of-trees, allowing clients to skip heavy computations for blocks or epochs that contain no data of interest to them.