From 7a9028334cd4084fab91ecd5a2606488bc65edb0 Mon Sep 17 00:00:00 2001 From: redshiftzero Date: Wed, 17 Apr 2024 17:28:30 -0400 Subject: [PATCH] spec: add community pool section --- docs/guide/src/pcli/governance.md | 53 ---------------- docs/protocol/src/SUMMARY.md | 7 ++- docs/protocol/src/community_pool.md | 60 +++++++++++++++++++ docs/protocol/src/community_pool/action.md | 7 +++ .../src/community_pool/action/deposit.md | 1 + .../src/community_pool/action/output.md | 1 + .../src/community_pool/action/spend.md | 1 + docs/protocol/src/stake/action.md | 2 +- 8 files changed, 77 insertions(+), 55 deletions(-) create mode 100644 docs/protocol/src/community_pool.md create mode 100644 docs/protocol/src/community_pool/action.md create mode 100644 docs/protocol/src/community_pool/action/deposit.md create mode 100644 docs/protocol/src/community_pool/action/output.md create mode 100644 docs/protocol/src/community_pool/action/spend.md diff --git a/docs/guide/src/pcli/governance.md b/docs/guide/src/pcli/governance.md index 467ef3dff3..6e3d84be6a 100644 --- a/docs/guide/src/pcli/governance.md +++ b/docs/guide/src/pcli/governance.md @@ -270,56 +270,3 @@ on the result of the vote: `proposal_N_passed`, `proposal_N_failed` or `proposal proposal was not slashed (that is, it passed _or_ failed), this action will also produce the original proposal deposit. Note that you _can_ claim a slashed proposal: you will receive the slashed proposal result NFT, but you will not receive the original proposal deposit. - -## Contributing To The Community Pool - -Anyone can contribute any amount of any denomination to the Penumbra Community Pool. To do this, use the -command `pcli tx community-pool-deposit`, like so: - -```bash -pcli tx community-pool-deposit 100penumbra -``` - -Funds contributed to the Community Pool cannot be withdrawn except by a successful Community Pool spend governance -proposal. - -To query the current Community Pool balance, use `pcli query community-pool balance` with the **base denomination** of an -asset or its asset ID (display denominations are not currently accepted). For example: - -```bash -pcli query Community Pool balance upenumbra -``` - -Community Pool spend proposals are only accepted for voting if they would not overdraw the current funds in the -Community Pool at the time the proposal is submitted, so it's worth checking this information before submitting -such a proposal. - -### Sending Validator Funding Streams To The Community Pool - -A validator may non-custodially send funds to the Community Pool, similarly to any other funding stream. To do -this, add a `[[funding_stream]]` section to your validator definition TOML file that declares the -Community Pool as a recipient for a funding stream. For example, your definition might look like this: - -```toml -sequence_number = 0 -enabled = true -name = "My Validator" -website = "https://example.com" -description = "An example validator" -identity_key = "penumbravalid1s6kgjgnphs99udwvyplwceh7phwt95dyn849je0jl0nptw78lcqqvcd65j" -governance_key = "penumbragovern1s6kgjgnphs99udwvyplwceh7phwt95dyn849je0jl0nptw78lcqqhknap5" - -[consensus_key] -type = "tendermint/PubKeyEd25519" -value = "tDk3/k8zjEyDQjQC1jUyv8nJ1cC1B/MgrDzeWvBTGDM=" - -# Send a 1% commission to this address: -[[funding_stream]] -recipient = "penumbrav2t1hum845ches70c8kp8zfx7nerjwfe653hxsrpgwepwtspcp4jy6ytnxhe5kwn56sku684x6zzqcwp5ycrkee5mmg9kdl3jkr5lqn2xq3kqxvp4d7gwqdue5jznk2ter2t66mk4n" -rate_bps = 100 - -# Send another 1% commission to the Community Pool: -[[funding_stream]] -recipient = "CommunityPool" -rate_bps = 100 -``` diff --git a/docs/protocol/src/SUMMARY.md b/docs/protocol/src/SUMMARY.md index df4ff97c54..dfb244cab3 100644 --- a/docs/protocol/src/SUMMARY.md +++ b/docs/protocol/src/SUMMARY.md @@ -67,7 +67,7 @@ - [Transaction Actions](./dex/action.md) - [`Swap`](./dex/action/swap.md) - [`SwapClaim`](./dex/action/swap_claim.md) - - [`Position` Actions](./dex/actions/position.md) + - [`Position` Actions](./dex/action/position.md) - [Staking and Delegation](./stake.md) - [Staking Tokens](./stake/tokens.md) - [Validator Rewards and Fees](./stake/validator-rewards.md) @@ -89,3 +89,8 @@ - [Transaction Actions](./ibc/action.md) - [`IbcRelay`](./ibc/action/ibc_relay.md) - [`Ics20Withdrawal`](./ibc/action/ics20_withdrawal.md) +- [Community Pool](./community_pool.md) + - [Transaction Actions](./community_pool/action.md) + - [`CommunityPoolSpend`](./community_pool/action/spend.md) + - [`CommunityPoolOutput`](./community_pool/action/output.md) + - [`CommunityPoolDeposit`](./community_pool/action/deposit.md) diff --git a/docs/protocol/src/community_pool.md b/docs/protocol/src/community_pool.md new file mode 100644 index 0000000000..b103f40a22 --- /dev/null +++ b/docs/protocol/src/community_pool.md @@ -0,0 +1,60 @@ +# Community Pool + +As with the Cosmos SDK, Penumbra also has a similar Community Pool feature. + +## Making A Community Pool Spend Transaction Plan + +Token holders can submit a governance community pool spend proposal. This proposal contains a _transaction plan_ containing a description of the spends to be performed if the proposal passes. This is described fully in the [governance section of the Penumbra protocol spec](./governance.md). + +## Contributing To The Community Pool + +Anyone can contribute any amount of any denomination to the Penumbra Community Pool. To do this, use the +command `pcli tx community-pool-deposit`, like so: + +```bash +pcli tx community-pool-deposit 100penumbra +``` + +Funds contributed to the Community Pool cannot be withdrawn except by a successful Community Pool spend governance +proposal. + +To query the current Community Pool balance, use `pcli query community-pool balance` with the **base denomination** of an +asset or its asset ID (display denominations are not currently accepted). For example: + +```bash +pcli query Community Pool balance upenumbra +``` + +Community Pool spend proposals are only accepted for voting if they would not overdraw the current funds in the +Community Pool at the time the proposal is submitted, so it's worth checking this information before submitting +such a proposal. + +### Sending Validator Funding Streams To The Community Pool + +A validator may non-custodially send funds to the Community Pool, similarly to any other funding stream. To do +this, add a `[[funding_stream]]` section to your validator definition TOML file that declares the +Community Pool as a recipient for a funding stream. For example, your definition might look like this: + +```toml +sequence_number = 0 +enabled = true +name = "My Validator" +website = "https://example.com" +description = "An example validator" +identity_key = "penumbravalid1s6kgjgnphs99udwvyplwceh7phwt95dyn849je0jl0nptw78lcqqvcd65j" +governance_key = "penumbragovern1s6kgjgnphs99udwvyplwceh7phwt95dyn849je0jl0nptw78lcqqhknap5" + +[consensus_key] +type = "tendermint/PubKeyEd25519" +value = "tDk3/k8zjEyDQjQC1jUyv8nJ1cC1B/MgrDzeWvBTGDM=" + +# Send a 1% commission to this address: +[[funding_stream]] +recipient = "penumbrav2t1hum845ches70c8kp8zfx7nerjwfe653hxsrpgwepwtspcp4jy6ytnxhe5kwn56sku684x6zzqcwp5ycrkee5mmg9kdl3jkr5lqn2xq3kqxvp4d7gwqdue5jznk2ter2t66mk4n" +rate_bps = 100 + +# Send another 1% commission to the Community Pool: +[[funding_stream]] +recipient = "CommunityPool" +rate_bps = 100 +``` diff --git a/docs/protocol/src/community_pool/action.md b/docs/protocol/src/community_pool/action.md new file mode 100644 index 0000000000..5de8b2992d --- /dev/null +++ b/docs/protocol/src/community_pool/action.md @@ -0,0 +1,7 @@ +# Transaction Actions + +The community pool component defines the following actions: + +- [`core.component.governance.v1.CommunityPoolDeposit`](./action/deposit.md) +- [`core.component.governance.v1.CommunityPoolOutput`](./action/output.md) +- [`core.component.governance.v1.CommunityPoolSpend`](./action/spend.md) diff --git a/docs/protocol/src/community_pool/action/deposit.md b/docs/protocol/src/community_pool/action/deposit.md new file mode 100644 index 0000000000..f3df36069b --- /dev/null +++ b/docs/protocol/src/community_pool/action/deposit.md @@ -0,0 +1 @@ +# CommunityPoolDeposit diff --git a/docs/protocol/src/community_pool/action/output.md b/docs/protocol/src/community_pool/action/output.md new file mode 100644 index 0000000000..24328cc855 --- /dev/null +++ b/docs/protocol/src/community_pool/action/output.md @@ -0,0 +1 @@ +# CommunityPoolOutput diff --git a/docs/protocol/src/community_pool/action/spend.md b/docs/protocol/src/community_pool/action/spend.md new file mode 100644 index 0000000000..93e7928a5f --- /dev/null +++ b/docs/protocol/src/community_pool/action/spend.md @@ -0,0 +1 @@ +# CommunityPoolSpend diff --git a/docs/protocol/src/stake/action.md b/docs/protocol/src/stake/action.md index 623388a545..bcbcf0b169 100644 --- a/docs/protocol/src/stake/action.md +++ b/docs/protocol/src/stake/action.md @@ -4,4 +4,4 @@ The staking component defines the following actions: - [`core.component.stake.v1.Delegate`](./action/delegate.md) - [`core.component.stake.v1.Undelegate`](./action/undelegate.md) -- [`core.component.stake.v1.UndelegateClaim`](./action/undelegateclaim.md) +- [`core.component.stake.v1.UndelegateClaim`](./action/undelegate_claim.md)