From 54b81fd4ff70eba97871ef876f521b4980ca0c62 Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 17 Jul 2024 20:09:53 -0700 Subject: [PATCH] rework users/pgf --- packages/docs/pages/users/_meta.json | 2 +- .../docs/pages/users/public-goods-funding.mdx | 17 +++ .../users/public-goods-funding/_meta.json | 4 + .../users/public-goods-funding/funding.mdx | 74 +++++++++++ .../users/public-goods-funding/stewards.mdx | 118 ++++++++++++++++++ .../pages/users/public-goods-stewards.mdx | 12 -- .../users/public-goods-stewards/_meta.json | 5 - .../users/public-goods-stewards/electing.mdx | 111 ---------------- .../users/public-goods-stewards/proposing.mdx | 70 ----------- .../users/public-goods-stewards/voting.mdx | 29 ----- 10 files changed, 214 insertions(+), 228 deletions(-) create mode 100644 packages/docs/pages/users/public-goods-funding.mdx create mode 100644 packages/docs/pages/users/public-goods-funding/_meta.json create mode 100644 packages/docs/pages/users/public-goods-funding/funding.mdx create mode 100644 packages/docs/pages/users/public-goods-funding/stewards.mdx delete mode 100644 packages/docs/pages/users/public-goods-stewards.mdx delete mode 100644 packages/docs/pages/users/public-goods-stewards/_meta.json delete mode 100644 packages/docs/pages/users/public-goods-stewards/electing.mdx delete mode 100644 packages/docs/pages/users/public-goods-stewards/proposing.mdx delete mode 100644 packages/docs/pages/users/public-goods-stewards/voting.mdx diff --git a/packages/docs/pages/users/_meta.json b/packages/docs/pages/users/_meta.json index ec178b6c..be2a0abe 100644 --- a/packages/docs/pages/users/_meta.json +++ b/packages/docs/pages/users/_meta.json @@ -5,7 +5,7 @@ "fees": "Fees on Namada", "delegators": "Bonding and Proof-of-stake", "governance": "Governance", - "public-goods-stewards": "Public Goods Funding (PGF)", + "public-goods-funding": "Public Goods Funding (PGF)", "ibc": "IBC transfers", "query": "Querying the Chain" } \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-funding.mdx b/packages/docs/pages/users/public-goods-funding.mdx new file mode 100644 index 00000000..c36b96d6 --- /dev/null +++ b/packages/docs/pages/users/public-goods-funding.mdx @@ -0,0 +1,17 @@ +# Public Goods Funding +Namada funds public goods by regularly minting NAM tokens into an on-chain PGF account and allocating certain amounts for certain entities. +The inflation rate is a constant parameter `pgf_inflation_rate` that is mutable by governance. + +The entities that receive such funding are approved either via governance or by a multisignature account known as a "public goods steward". +Stewards must also be elected with a governance proposal and are meant to be trusted authorities for responsibly identifying good candidates to receive public goods funding. +As such, a steward may submit a funding proposal that does not need to receive any yay votes to be passed, though a community veto mechanism does exist. + +To incentivize high-impact authorities to seek stewardship, a steward also receives inflationary NAM tokens at a rate dictated by the constant parameter that is chosen by governance. + +See the specs about the public goods funding [here](https://specs.namada.net/modules/governance/public-goods-funding.html) for more details. + +This documentation will cover: + +1. [Becoming a steward (and other rules)](./public-goods-stewards/electing.mdx). +2. [How to submit a public goods funding proposal](./public-goods-stewards/proposing.mdx) +3. [How to vote on steward elections](./public-goods-stewards/voting.mdx#voting-for-stewards) as well as [public goods funding proposals](./public-goods-stewards/voting.mdx#voting-for-pgf-proposals). \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-funding/_meta.json b/packages/docs/pages/users/public-goods-funding/_meta.json new file mode 100644 index 00000000..8359ffb6 --- /dev/null +++ b/packages/docs/pages/users/public-goods-funding/_meta.json @@ -0,0 +1,4 @@ +{ + "stewards": "Stewards", + "funding": "PGF funding proposals" +} \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-funding/funding.mdx b/packages/docs/pages/users/public-goods-funding/funding.mdx new file mode 100644 index 00000000..f007cc05 --- /dev/null +++ b/packages/docs/pages/users/public-goods-funding/funding.mdx @@ -0,0 +1,74 @@ +import { Callout } from 'nextra-theme-docs' + +# Proposing funding +Namada has two different types of public goods funding: continuous and retroative. + +Recipients of continuous PGF receive tokens at the beginning of every epoch when inflation is minted. + +Recipients of retroactive PGF receive tokens in a one-time transfer upon the successful execution of such a governance proposal, which also would occur at the beginning of an epoch. + +In both cases of PGF, the recipient addresses can be either native Namada addresses or addresses on other IBC-compatible blockchains that have open channels with Namada. + +## Submitting the funding proposal + +A funding proposal can be submitted with the following CLI command: + +```shell copy +namada client init-proposal \ + --pgf-funding \ + --data-path funding_proposal.json +``` + +The structure of `funding_proposal.json` is demonstrated with the following example: + +```json +{ + "proposal": { + "content": { + "title": "Fund Jonny's cryptography PhD", + "authors": "stewie@heliax.dev", + "discussions-to": "forum.namada.net/t/jonny-cryptography/1", + "created": "2024-01-01T00:00:01Z", + "license": "MIT", + "abstract": "Fund Jonny's cryptography PhD focusing on elliptic curves.", + "motivation": "Jonny is the world's most promising cryptography prodigy.", + "details": "It is important for humanity to support Jonny in his cryptography research.", + "author": "tnam1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn", + "voting_start_epoch": 3, + "voting_end_epoch": 6, + "activation_epoch": 12 + }, + "data": { + "continuous": [ + { + "Internal": { + "amount": "1000", + "target": "tnam1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzaaaaa" + } + } + ], + "retro": [ + { + "Internal": { + "amount": "1500", + "target": "tnam1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzaaaaa" + } + } + ] + } +} +``` + +In the `"data"` section, both the `"continuous"` and `"retro"` fields contain a list of PGF targets. +The `"Internal"` keyword is used to indicate on-chain funding in the native token, whereas for funding over IBC to another chain, the `"IBC"` keyword would be used. +The attributes of an `"IBC"` object look like [this](../governance/proposal-types.mdx#ibc-pgf-proposals). + +The value in the `"amount"` attribute is the raw token amount in that token's denomination. +So in the example above for a PGF funding in the native NAM token, the amount `1000` corresponds to `0.001 NAM`, since the Namada token denomination is `6`. + +## Voting on the funding proposal +Voting on the funding proposal is done the same way as any other normal proposal, as described [here](../governance/governance-actions.mdx#vote-on-a-proposal). + +If a funding proposal was submitted by a PGF steward, then voting on the proposal is not needed, as a steward funding proposal requires no `yay` votes to pass. +However, this kind of funding proposal can be vetoed by the community if the proposal receives more `nay` votes than `1/3` of the total active voting power. +Additionally, if the proposal receives at least as many `nay` votes as `2/3` of the total active voting power, then the steward account will be removed from the set of PGF stewards. \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-funding/stewards.mdx b/packages/docs/pages/users/public-goods-funding/stewards.mdx new file mode 100644 index 00000000..6a580b00 --- /dev/null +++ b/packages/docs/pages/users/public-goods-funding/stewards.mdx @@ -0,0 +1,118 @@ +import { Callout } from 'nextra-theme-docs' + +# Stewards + +A public goods steward can consist of an arbitrary number of people or can be a single person. +The only requirement is that the steward's multisignature account is elected by the community through a governance proposal. + +For this reason, the first step to becoming a steward is to create a multisignature account. +This can be done using the commands found in the [multisignature documentation](../transparent-accounts/multisignature.mdx). + +No more than `maximum_number_of_stewards` are allowed to exist at any given time; this parameter that controls the upper bound on stewards can be changed via governance. + +## Becoming a steward +Once the multisig account is created, the steward can submit a governance proposal to nominate themselves for election as a steward. +A steward proposal to elect a multisig account may only be submitted by that same account. + +### Submitting a steward governance proposal +A special governance proposal must be submitted in order to elect a steward. This is done with the following command: + +```shell copy +namadac init-proposal \ + --pgf-stewards \ + --data-path $PATH_TO/steward_proposal.json +``` +where `$PATH_TO/steward_proposal.json` is the path to the `steward_proposal.json` file. + +The structure of the proposal `steward_proposal.json` looks like a default proposal but with an altered `"data"` section: + +```json +{ + "proposal" :{ + "content": { + "title": "Stewie for Steward", + "authors": "stewie@heliax.dev", + "discussions-to": "forum.namada.net/t/stewies-manifesto/1", + "created": "2024-01-01T00:00:01Z", + "license": "MIT", + "abstract": "Stewie is an expert in zero-knowledge cryptography that would like to identify influential cryptographers to receive funding to continue their work.", + "motivation": "Funding cryptography research will help Namada and other blockchain projects innovate and flourish.", + "details": "We will describe here certain areas of ZK research that should receive funding." + }, + "author": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn", + "voting_start_epoch": 3, + "voting_end_epoch": 6, + "activation_epoch": 12 + }, + "data" : { + "add" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn", + "remove": [] + } +} +``` + +The `"data"` field contains the structure that allows either the addition or removal of +a multisignature account from the list of stewards. In this case, the `"action"` is `"add"`, +and the `"address"` is the address of the multisignature account that will be elected as a steward. +In this case, the proposal does not call to remove any stewards, and so this field is an empty list `[]`. +A steward proposal may propose to remove more than one steward at a time. + + +In the motivation and abstract field, it is important to make clear what type of +public goods funding the steward will be focusing on. +The *areas of public goods funding* can be found in the +[public goods funding specs](https://specs.namada.net/modules/governance/public-goods-funding.html#funding-focuses). + + +### Becoming elected + +Once the proposal is submitted, it will be voted on by the community (see [voting](./voting.mdx)) like any other governance proposal. + +Once a multisignature account is elected (which occurs at the beginning of the `activation_epoch`), it will be able to submit proposals to the public goods funding pool (see [submitting proposals](./proposing.mdx#proposing-funding)). + +## Removing stewards + +There are 4 ways that a steward can lose their stewardship: + +#### 1. Resign as a steward +A steward account may resign their position at any point. Through the CLI it can be done with the command: + +```shell copy +namadac resign-steward --steward $STEWARD_ADDRESS +``` + +#### 2. Funding proposal veto with removal +If a steward submits a funding proposal that receives at least as many `nay` votes as `2/3` of the total active voting power, then the steward is immediately removed in addition to the veto of the proposal. + +#### 3. Removal through a governance proposal +A steward may be removed by a steward governance proposal as described [above](./stewards.mdx#submitting-a-steward-governance-proposal). +For removal, the `"remove"` list within the `"data"` field of the json file would contain the relevant steward address. + +#### 4. They reach the end of their term +TODO: are stewards elected for a certain term? + +## Steward inflation +A PGF steward also receives inflationary NAM tokens at the beginning of every epoch. +The steward inflation rate is a constant parameter `stewards_inflation_rate` that can be changed via governance. + +Each PGF steward receives an inflation amount according to `stewards_inflation_rate`; this amount is given to each steward and not divided among them. + +#### Steward's reward distribution +A steward may also designate certain portions of its steward inflation to be minted to other addresses. +This distribution can be set with the following steward commission CLI command: + +```shell copy +namadac update-steward-rewards --steward $STEWARD_ADDRESS --data-path $PATH_TO/steward_rewards.json +``` + +The file `steward_rewards.json` contains the desired reward distribution with the structure: + +```json +{ + "reward_distribution": { + "tnam...aaa": "0.3", + "tnam...bbb": "0.3", + "tnam...ccc": "0.4" + } +} +``` diff --git a/packages/docs/pages/users/public-goods-stewards.mdx b/packages/docs/pages/users/public-goods-stewards.mdx deleted file mode 100644 index faf55506..00000000 --- a/packages/docs/pages/users/public-goods-stewards.mdx +++ /dev/null @@ -1,12 +0,0 @@ -# Public Goods Stewards Documentation -The funding of public goods on Namada is conducted through an entity called the "public goods stewards". Each public goods steward is a [multisignature account](./transparent-accounts/multisignature.mdx). - -Each steward is elected by governance through separate governance proposals. - -See the specs about the public goods funding [here](https://specs.namada.net/modules/governance/public-goods-funding.html) for more details. - -This documentation will cover: - -1. [How to become a public goods steward](./public-goods-stewards/electing.mdx). -2. [How to submit a public goods funding proposal](./public-goods-stewards/proposing.mdx) -3. [How to vote on steward elections](./public-goods-stewards/voting.mdx#voting-for-stewards) as well as [public goods funding proposals](./public-goods-stewards/voting.mdx#voting-for-pgf-proposals). \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-stewards/_meta.json b/packages/docs/pages/users/public-goods-stewards/_meta.json deleted file mode 100644 index 31af00dc..00000000 --- a/packages/docs/pages/users/public-goods-stewards/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "electing": "Becoming a Steward", - "voting": "Voting for Stewards and PGF proposals", - "proposing": "PGF proposals" -} diff --git a/packages/docs/pages/users/public-goods-stewards/electing.mdx b/packages/docs/pages/users/public-goods-stewards/electing.mdx deleted file mode 100644 index 07dccf1b..00000000 --- a/packages/docs/pages/users/public-goods-stewards/electing.mdx +++ /dev/null @@ -1,111 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# Becoming a steward - -A public goods steward can consist of an arbitrary number of people, and can be a single person. The only requirement is that the steward's multisignature account is elected by the community, through a governance proposal. - -For this reason, the first step to becoming a steward is to create a multisignature account. -This can be done using the commands found in the [multisgnature documentation](../transparent-accounts/multisignature.mdx). - -Once the multisig account is created, the steward can submit a governance proposal to elect the account as a steward. - -## Governance proposal - -The governance proposal required to elect a new steward is `StewardProposal`. - -### Crafting the `proposal.json` file for a `StewardProposal` - -The `steward_proposal.json` file contains the information about the proposal. It is a JSON file with the following structure: - -```json -{ - "proposal" :{ - "id": 1, - "content": { - "title": "Stewie for Steward 2024", - "authors": "stewie@heliax.dev", - "discussions-to": "forum.namada.net/t/stewies-manifesto/1", - "created": "2024-01-01T00:00:01Z", - "license": "MIT", - "abstract": "Stewie is running for steward, with a focus on technical research. The technical research I will be focused on will definitely not be for weapons of mass destruction. There is some possibility however that I may be focusing somewhat on open source software for weapons of mass destruction.", - "motivation": "Nobody knows technical research better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again", - "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction" - }, - "author": "stewie", - "voting_start_epoch": 3, - "voting_end_epoch": 6, - "grace_epoch": 12 - }, - "data" : { - "add" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn", - "remove": [] - } -} -``` - -The `"data"` field contains the structure that allows either the addition or removal of -a multisignature account from the list of stewards. In this case, the `"action"` is `"add"`, -and the `"address"` is the address of the multisignature account that will be elected as a steward. -If the `"action"` was `"remove"`, the `"address"` would be the address of the multisignature account -that would be removed from the list of stewards. - - -In the motivation and abstract field, it is important to make clear what type of -public goods funding the steward will be focusing on. -The *areas of public goods funding* can be found in the -[public goods funding specs](https://specs.namada.net/modules/governance/public-goods-funding.html#funding-focuses). - - -### Submitting the proposal to the ledger - -The CLI command to submit a proposal is: - -```shell copy -namadac init-proposal \ - --pgf-stewards \ - --data-path $PATH_TO/steward_proposal.json -``` -where `$PATH_TO/steward_proposal.json` is the path to the `steward_proposal.json` file. - -### Becoming elected - -Once the proposal is submitted, it will be voted on by the community (see [voting](./voting.mdx)). If the proposal passes, the account will become a steward. If the proposal fails, the account will not become a steward. - -Once a multisignature account becomes elected (which will happen at the end of the `grace_epoch`), it will be able to submit proposals to the public goods funding pool (see [submitting proposals](./proposing.mdx#proposing-funding)). - -## Losing stewardship - -There are 4 ways that a steward can lose their stewardship: - -1. Resign as a steward -2. Have a significantly failed funding proposal ($/frac{2}{3}$ of the community votes, and out of these, $/frac{2}{3}$ vote against the proposal) -3. Become voted out through a governance proposal -4. They reach the end of their term - -Resigning as a steward can be done at any point. -Through the CLI it can be done with the command: - -```shell copy -namadac resign-steward --steward $STEWARD_ADDRESS -``` - -Read more about the other methods of losing stewardship in the [specs](https://specs.namada.net/modules/goverance/public-goods-funding/becoming-a-steward#losing-stewardship-status). - -## Update steward commissions - -The `commissions.json` file contains the information about the reward distribution. It is a JSON file with the following structure: - -```json -{ - "reward_distribution": { - "tnam...": "1" - } -} -``` - -Update steward commissions can be done at any point. -Through the CLI it can be done with the command: - -```shell copy -namadac update-steward-rewards --steward $STEWARD_ADDRESS --data-path $PATH_TO/commissions.json -``` \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-stewards/proposing.mdx b/packages/docs/pages/users/public-goods-stewards/proposing.mdx deleted file mode 100644 index 33a6c61e..00000000 --- a/packages/docs/pages/users/public-goods-stewards/proposing.mdx +++ /dev/null @@ -1,70 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# Proposing funding - -## Formatting the `proposal.json` - -Below is an example of a `PGFProposal` that a governance participant could submit. -```json -{ - "proposal": { - "id": 1, - "content": { - "title": "Stewie for Steward 2024", - "authors": "stewie@heliax.dev", - "discussions-to": "forum.namada.net/t/stewies-manifesto/1", - "created": "2024-01-01T00:00:01Z", - "license": "MIT", - "abstract": "Stewie is running for steward, with a focus on technical research. The technical research I will be focused on will definitely not be for weapons of mass destruction. There is some possibility however that I may be focusing somewhat on open source software for weapons of mass destruction.", - "motivation": "Nobody knows technical research better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again", - "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction" - }, - "author": "", - "voting_start_epoch": 3, - "voting_end_epoch": 6, - "grace_epoch": 12 - }, - "data": { - "continuous": [ - { - "Internal": { - "amount": "1000", - "target": "" - } - } - ], - "retro": [ - { - "Internal": { - "amount": "1500", - "target": "" - } - } - ] - } -} -``` -where `` should be changed to the address of the recipient of the funds. - -Save this file as `PGF_proposal.json` to some memorable path on your machine. - -## Submitting the proposal - -In order to submit the proposal, the governance participant can use the following command: - -```shell copy -namada client init-proposal \ - --pgf-funding \ - --data-path PGF_proposal.json -``` - -The proposal will then be given a `proposal-id` which can be used to query the proposal. - -## Querying the proposal - -The command for querying the proposal is as follows: - -```shell copy -namada client query-proposal \ - --proposal-id -``` diff --git a/packages/docs/pages/users/public-goods-stewards/voting.mdx b/packages/docs/pages/users/public-goods-stewards/voting.mdx deleted file mode 100644 index 44b54582..00000000 --- a/packages/docs/pages/users/public-goods-stewards/voting.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Voting for stewards and PGF proposals - -## Voting for stewards - -Any user is allowed (and encouraged) to vote for potential PGF stewards. Once the steward has submitted their proposal to the ledger, the community can vote on it. The voting process is the same as for any other proposal, but the proposal type is `StewardProposal`. - -The CLI command for voting for a steward is: - -```shell copy -namada client vote-proposal \ - --proposal-id \ - --address your-established-account \ - --vote yay \ - --signing-keys -``` - -In order to vote against the proposal, replace `yay` with `nay`. - -## Voting for PGF proposals - -Similarly, the command for voting for PGF proposals is: - -```shell copy -namada client vote-proposal \ - --proposal-id \ - --address your-established-account \ - --vote yay \ - --signing-keys -``` \ No newline at end of file