Skip to content
Snippets Groups Projects
Commit 582a46c2 authored by Hugo Trentesaux's avatar Hugo Trentesaux
Browse files

doc refac (!306) 

* refac generated doc, keep only user calls

* refac doc homepage

* remove mirror and smith doc that was moved to https://duniter.org/wiki/duniter-v2/

and nginx which is out of topic
parent 33060a55
No related branches found
No related tags found
1 merge request!306doc refac
Pipeline #39528 waiting for manual action
Stage: quality
Stage: build
Stage: tests
Stage: deploy
Expand all Show whitespace changes
Inline Side-by-side
Showing
with 373 additions and 1477 deletions
README.md
+ 34
− 188
View file @ 582a46c2
......@@ -10,40 +10,46 @@
<img alt="logov2" src="https://duniter.fr/img/duniterv2.svg" width="128" height="128"/>
</div>
## Documentation TOC
Full up to date technical doc (auto-generated) : https://doc-duniter-org.ipns.pagu.re/gdev_runtime/
## Documentation
- [README](./README.md)
Multiple documentation sources are available depending on the level of detail you need.
- Full technical Rust doc (auto-generated with `cargo xtask gen-doc`) : https://doc-duniter-org.ipns.pagu.re/duniter/
- User and client developer doc (official website) : https://duniter.org/wiki/duniter-v2/
- Internal documentation (within git repository), see table of contents below : [./doc](./doc)
### Internal documentation TOC
- [README](./README.md) (this file)
- [Use](#use)
- [Test](#test)
- [Contribute](#contribute)
- [Structure](#project-structure)
- [docker](./docker/) docker-related documentation
- [docs](./docs/)
- [api](./docs/api/)
- [manual](./docs/api/manual.md)
- [License](#license)
- [docs](./docs/) internal documentation
- [api](./docs/api/) API
- [manual](./docs/api/manual.md) manage account and identities
- [runtime-calls](./docs/api/runtime-calls.md) the calls you can submit through the RPC API
- [runtime-errors](./docs/api/runtime-errors.md) the errors you can get submitting a call
- [runtime-events](./docs/api/runtime-events.md) the events you can get submitting a call
- [dev](./docs/dev/)
- [dev](./docs/dev/) developer documentation
- [beginner-walkthrough](./docs/dev/beginner-walkthrough.md)
- [git-conventions](./docs/dev/git-conventions.md)
- [pallet_conventions](./docs/dev/pallet_conventions.md)
- [launch-a-live-network](./docs/dev/launch-a-live-network.md)
- [setup](./docs/dev/setup.md)
- [compilation features](./docs/dev/compilation.md)
- [verify-runtime-code](./docs/dev/verify-runtime-code.md)
- [weights-benchmarking](./docs/dev/weights-benchmarking.md)
- [upgrade-substrate](./docs/dev/upgrade-substrate.md)
- [test](./docs/test/)
- [replay-block](./docs/test/replay-block.md)
- [user](./docs/user/)
- [user](./docs/user/) user documentation
- [autocompletion](./docs/user/autocompletion.md)
- [mirror](./docs/user/mirror.md) deploy a permanent ǦDev mirror node
- [smith](./docs/user/smith.md) deploy a permanent ǦDev validator node
- [debian installation](./docs/user/installation_debian.md)
- [packaging](./docs/packaging/)
- [build-for-arm](./docs/packaging/build-for-arm.md)
- [distance](./docs/user/distance.md)
- [fees](./docs/user/fees.md)
- [packaging](./docs/packaging/) packaging
- [build-for-arm](./docs/packaging/build-for-arm.md) build for ARM architecture
- [build-debian](./docs/packaging/build-deb.md) build a native Debian package
- [docker](./docker/) docker-related documentation
- [end2end-tests](./end2end-tests/) automated end to end tests written with cucumber
- [live-tests](./live-tests/) sanity checks to test the storage of a live chain
......@@ -53,23 +59,23 @@ Full up to date technical doc (auto-generated) : https://doc-duniter-org.ipns.pa
The easiest way is to use the docker image.
Minimal command to deploy a **temporary** mirror peer:
Minimal command to deploy a temporary mirror peer:
```docker
docker run -it -p9944:9944 -e DUNITER_CHAIN_NAME=gdev duniter/duniter-v2s:v0.4.0 --tmp --execution=Wasm
docker run -it -p9944:9944 -e DUNITER_CHAIN_NAME=gdev duniter/duniter-v2s-gdev-800:latest
```
To go further, read [How to deploy a permanent mirror node on ĞDev network](./docs/user/rpc.md).
To go further, read [How to deploy a permanent mirror node on ĞDev network 🔗](https://duniter.org/wiki/duniter-v2/#run-a-mirror-node).
### Create your local blockchain
It can be useful to deploy your local blockchain, for instance to have a controlled environment to develop/test an application that interacts with the blockchain.
```docker
docker run -it -p9944:9944 duniter/duniter-v2s:v0.4.0 --tmp
docker run -it -p9944:9944 duniter/duniter-v2s-gdev-800:latest
```
Or use the `docker-compose.yml` at the root of this repository.
Or use the [`docker-compose.yml`](./docker-compose.yml) at the root of this repository.
#### Control when your local blockchain should produce blocks
......@@ -80,34 +86,9 @@ You can decide when to produce blocks with the cli option `--sealing` which has
- `--sealing=instant`: produce a block immediately upon receiving a transaction into the transaction pool
- `--sealing=manual`: produce a block upon receiving an RPC request (method `engine_createBlock`).
### Autocompletion
See [autocompletion](./docs/user/autocompletion.md).
### Shell autocompletion
## Test
### Test a specific commit
At each commit on master, an image with the tag `debug-sha-********` is published, where `********`
corresponds to the first 8 hash characters of the commit.
Usage:
```docker
docker run -it -p9944:9944 --name duniter-v2s duniter/duniter-v2s:debug-sha-b836f1a6
```
Then open `https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944` in a browser.
Enable detailed logging:
```docker
docker run -it -p9944:9944 --name duniter-v2s \
-e RUST_LOG=debug \
-e RUST_BACKTRACE=1 \
-lruntime=debug \
duniter/duniter-v2s:debug-sha-b836f1a6
```
See [autocompletion](./docs/user/autocompletion.md) to generate shell autocompletion for duniter commands.
## Contribute
......@@ -134,20 +115,11 @@ cargo build
Use Rust's native `cargo` command to build and launch the node:
```sh
cargo run -- --dev --tmp
cargo run -- --dev
```
This will deploy a local blockchain with test accounts (Alice, Bob, etc) in the genesis.
## Single-Node Development Chain
This command will start the single-node development chain with persistent state:
```bash
./target/debug/duniter --dev --tmp
```
Then open `https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944` in a browser.
Open `https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944` to watch and interact with your node.
Start the development chain with detailed logging:
......@@ -155,138 +127,11 @@ Start the development chain with detailed logging:
RUST_LOG=debug RUST_BACKTRACE=1 ./target/debug/duniter -lruntime=debug --dev
```
## Multi-Node Local Testnet
If you want to see the multi-node consensus algorithm in action, refer to
[our Start a Private Network tutorial](https://substrate.dev/docs/en/tutorials/start-a-private-network/).
### Purge previous local testnet
```
./target/debug/duniter purge-chain --base-path /tmp/alice --chain local
./target/debug/duniter purge-chain --base-path /tmp/bob --chain local
```
### Start Alice's node
```bash
./target/debug/duniter \
--base-path /tmp/alice \
--chain local \
--alice \
--port 30333 \
--rpc-port 9944 \
--node-key 0000000000000000000000000000000000000000000000000000000000000001 \
--validator
```
### Start Bob's node
## License
```bash
./target/debug/duniter \
--base-path /tmp/bob \
--chain local \
--bob \
--port 30334 \
--rpc-port 9945 \
--validator \
--bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp
```
See [LICENSE](./LICENSE)
## Project Structure
A Substrate project such as this consists of a number of components that are spread across a few
directories.
### Node
A blockchain node is an application that allows users to participate in a blockchain network.
Substrate-based blockchain nodes expose a number of capabilities:
- Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking stack to allow the
nodes in the network to communicate with one another.
- Consensus: Blockchains must have a way to come to
[consensus](https://substrate.dev/docs/en/knowledgebase/advanced/consensus) on the state of the
network. Substrate makes it possible to supply custom consensus engines and also ships with
several consensus mechanisms that have been built on top of
[Web3 Foundation research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html).
- RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes.
There are several files in the `node` directory - take special note of the following:
- [`chain_spec.rs`](./node/src/chain_spec.rs): A
[chain specification](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec) is a
source code file that defines a Substrate chain's initial (genesis) state. Chain specifications
are useful for development and testing, and critical when architecting the launch of a
production chain. Take note of the `development_chain_spec` and `testnet_genesis` functions, which
are used to define the genesis state for the local development chain configuration. These
functions identify some
[well-known accounts](https://substrate.dev/docs/en/knowledgebase/integrate/subkey#well-known-keys)
and use them to configure the blockchain's initial state.
- [`service.rs`](./node/src/service.rs): This file defines the node implementation. Take note of
the libraries that this file imports and the names of the functions it invokes. In particular,
there are references to consensus-related topics, such as the
[longest chain rule](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#longest-chain-rule),
the [Babe](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#babe) block authoring
mechanism and the
[GRANDPA](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#grandpa) finality
gadget.
After the node has been [built](#build), refer to the embedded documentation to learn more about the
capabilities and configuration parameters that it exposes:
```shell
./target/debug/duniter --help
```
### Runtime
In Substrate, the terms
"[runtime](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#runtime)" and
"[state transition function](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#stf-state-transition-function)"
are analogous - they refer to the core logic of the blockchain that is responsible for validating
blocks and executing the state changes they define. The Substrate project in this repository uses
the [FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame) framework to construct a
blockchain runtime. FRAME allows runtime developers to declare domain-specific logic in modules
called "pallets". At the heart of FRAME is a helpful
[macro language](https://substrate.dev/docs/en/knowledgebase/runtime/macros) that makes it easy to
create pallets and flexibly compose them to create blockchains that can address
[a variety of needs](https://www.substrate.io/substrate-users/).
Review the [FRAME runtime implementation](./runtime/src/lib.rs) included in this template and note
the following:
- This file configures several pallets to include in the runtime. Each pallet configuration is
defined by a code block that begins with `impl $PALLET_NAME::Config for Runtime`.
- The pallets are composed into a single runtime by way of the
[`construct_runtime!`](https://crates.parity.io/frame_support/macro.construct_runtime.html)
macro, which is part of the core
[FRAME Support](https://substrate.dev/docs/en/knowledgebase/runtime/frame#support-library)
library.
### Pallets
The runtime in this project is constructed using many FRAME pallets that ship with the
[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a
template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory.
A FRAME pallet is compromised of a number of blockchain primitives:
- Storage: FRAME defines a rich set of powerful
[storage abstractions](https://substrate.dev/docs/en/knowledgebase/runtime/storage) that makes
it easy to use Substrate's efficient key-value database to manage the evolving state of a
blockchain.
- Dispatchables: FRAME pallets define special types of functions that can be invoked (dispatched)
from outside of the runtime in order to update its state.
- Events: Substrate uses [events](https://substrate.dev/docs/en/knowledgebase/runtime/events) to
notify users of important changes in the runtime.
- Errors: When a dispatchable fails, it returns an error.
- Config: The `Config` configuration interface is used to define the types and parameters upon
which a FRAME pallet depends.
## License
CopyLeft 2021-2023 Axiom-Team
Some parts borrowed from Polkadot (Parity Technologies (UK) Ltd.)
......@@ -302,3 +147,4 @@ GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with Duniter-v2S. If not, see <https://www.gnu.org/licenses/>.
```
docker-compose.yml
+ 1
− 1
View file @ 582a46c2
......@@ -5,7 +5,7 @@ services:
container_name: duniter-v2s-mirror
# the image tells which network you are connecting to
# here it is gdev network
image: duniter/duniter-v2s-gdev:latest
image: duniter/duniter-v2s-gdev-800:latest
ports:
# prometheus telemetry to monitor resource use
- 9615:9615
......
docker/compose/docker-compose.smith.yml
+ 1
− 1
View file @ 582a46c2
......@@ -4,7 +4,7 @@ services:
# duniter smith node
duniter-v2s-smith:
container_name: duniter-v2s-smith
image: duniter/duniter-v2s-gdev:latest
image: duniter/duniter-v2s-gdev-800:latest
ports:
# RPC API of a smith node should not be exposed publicly!
- 127.0.0.1:9944:9944
......
docs/api/manual.md
+ 15
− 13
View file @ 582a46c2
......@@ -3,7 +3,7 @@
This functional documentation presents how wallets can interact with the blockchain.
It is intended to complete the [runtime calls documentation](./runtime-calls.md) in a runtime-specific way to fit the real needs of wallet developers.
Only ĞDev is covered for now.
NOTE : a more detailed doc is available at <https://duniter.org/wiki/duniter-v2/doc/>
## Notations
......@@ -11,26 +11,27 @@ Only ĞDev is covered for now.
## Account existence
An account exists if and only if it contains at least the existential deposit (2 ĞD).
An account exists if and only if it contains at least the existential deposit (`balances.existentialDeposit` = 1 ĞD).
## Become member
Only use `identity` pallet. The `membership` calls are disabled.
Only use `identity` pallet.
1. The account that wants to gain membership needs to exists.
1. Any account that already has membership and respects the identity creation period can create an identity for another account, using `identity.createIdentity`.
1. The account has to confirm its identity with a name, using `identity.confirmIdentity`. The name must be ASCII alphanumeric, punctuation or space characters: `` /^[-!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~a-zA-Z0-9 ]{3,64}$/ `` (additionally, trailing spaces and double spaces are forbidden, as a phishing countermeasure). If the name is already used, the call will fail.
1. 4 different member accounts must certify the account using `cert.addCert`.
1. The distance evaluation must be requested for the pending identity using `distance.evaluateDistance`.
1. 3 sessions later, if the distance rule is respected, `identity.validateIdentity` can be called.
1. The distance evaluation must be requested for the pending identity using `distance.requestDistanceEvaluation`.
1. 3 distance sessions later, if the distance rule is respected, identity is validated automatically.
## Change key
A member can request a key change via the `identity.change_onwner_key` call. It needs the following SCALE encoded (see SCALE encoding section below) payload:
* The new owner key payload prefix (rust definition: `b"icok"`)
* the genesis block hash. (rust type `[u8; 32]` (`H256`))
* The identity index (rust type `u64`)
* The old key (rust type `u64`)
- The new owner key payload prefix (rust definition: `b"icok"`)
- the genesis block hash. (rust type `[u8; 32]` (`H256`))
- The identity index (rust type `u64`)
- The old key (rust type `u64`)
This payload must be signed with the new key.
......@@ -43,9 +44,10 @@ This feature is useful in case the user has lost their private key since the rev
### Generate the revocation payload
The revocation needs this SCALE encoded (see SCALE encoding section below) payload:
* The revocation payload prefix (rust definition: `b"revo"`)
* The identity index (rust type `u64`)
* the genesis block hash. (rust type `[u8; 32]` (`H256`))
- The revocation payload prefix (rust definition: `b"revo"`)
- The identity index (rust type `u64`)
- the genesis block hash. (rust type `[u8; 32]` (`H256`))
This payload must be signed with the corresponding revocation key.
......
docs/api/runtime-calls.md
+ 255
− 1062
View file @ 582a46c2
This diff is collapsed.
docs/api/runtime-errors.md
+ 8
− 1
View file @ 582a46c2
# Runtime errors
There are **190** errors from **35** pallets.
There are **191** errors from **35** pallets.
<ul>
<li>System - 0
......@@ -986,6 +986,13 @@ Insufficient balance to create an identity.
Owner key currently used as validator.
</details>
</li>
<li>
<details>
<summary>
<code>InvalidLegacyRevocationFormat</code> - 19</summary>
Legacy revocation document format is invalid
</details>
</li>
</ul>
</li>
<li>Membership - 42
......
docs/api/runtime-errors.po
+ 2
− 0
View file @ 582a46c2
......@@ -254,6 +254,8 @@ msgid "Identity.InsufficientBalance"
msgstr "Insufficient balance to create an identity."
msgid "Identity.OwnerKeyUsedAsValidator"
msgstr "Owner key currently used as validator."
msgid "Identity.InvalidLegacyRevocationFormat"
msgstr "Legacy revocation document format is invalid"
msgid "Membership.MembershipNotFound"
msgstr "Membership not found, can not renew."
msgid "Membership.AlreadyMember"
......
docs/test/replay-block.md → docs/dev/replay-block.md
+ 2
− 0
View file @ 582a46c2
# How to replay a block
WARN: try-runtime is not properly implemented
You can use `try-runtime` subcommand to replay a block against a real state from a live network.
1. Checkout the git tag of the runtime version at the block you want to replay
......
docs/user/mirror.md deleted 100644 → 0
+ 0
− 21
View file @ 33060a55
# How to deploy a permanent rpc node on ĞDev network
## Publish a node
### Duniter part
See [docker documentation](../../docker/README.md) to install, configure, and start a node.
### Reverse proxy part
See [nginx reverse proxy](./nginx_reverse_proxy.md).
To go further, read [How to become a (black)smith](./smith.md)
## Upgrade your node with minimal interruption
1. Modify docker image tag on your compose file
2. Run `docker compose pull`, this will pull the new image.
3. Run `docker compose up -d --remove-orphans`, this will recreate the container
4. Verify that your node restarted well `docker compose logs duniter-rpc`
5. Remove the old image `docker rmi duniter/duniter-v2s:OLD_TAG`
docs/user/nginx_reverse_proxy.md deleted 100644 → 0
+ 0
− 54
View file @ 33060a55
# Nginx reverse proxy example
In `/etc/nginx/sites-enabled/gdev.YOUR_DOMAIN` put (you can probably do simpler):
```nginx
# see http://nginx.org/en/docs/http/websocket.html
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
server_name gdev.YOUR_DOMAIN.fr;
listen 443 ssl http2;
listen [::]:443 ssl http2;
ssl_certificate /etc/nginx/ssl/YOUR_DOMAIN.cert;
ssl_certificate_key /etc/nginx/ssl/YOUR_DOMAIN.key;
root /nowhere;
add_header X-Frame-Options SAMEORIGIN;
add_header X-XSS-Protection "1; mode=block";
proxy_redirect off;
proxy_buffering off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
proxy_read_timeout 90;
location / {
proxy_pass http://localhost:9944;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_http_version 1.1;
proxy_read_timeout 1200s;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
}
}
```
and replace `YOUR_DOMAIN` by your domain each time.
- [generate your ssl certificates](https://github.com/acmesh-official/acme.sh) with let's encrypt
if you don't already have a wildcard certificate.
- `service nginx reload`
Your node is now online as a rpc node. It's fully capable for wallet use.
docs/user/smith.md deleted 100644 → 0
+ 0
− 51
View file @ 33060a55
# How to become a (black)smith
## Publish a node
### Duniter part
See [docker documentation](../../docker/README.md) to install, configure, and start a node. For a smith node, you want to set `DUNITER_VALIDATOR` to `true`.
### Reverse proxy part
See [nginx reverse proxy](./nginx_reverse_proxy.md).
## Join the Smith WoT
Only members of the smith WoT can author blocks. This WoT is a subset of the main WoT, hence before joining it you need to join the main WoT.
1. Create an SSH bridge from your computer to your server: `ssh -L 9945:localhost:9945 SSH_USER@YOUR_SERVER`
2. Install PolkadotJS browser extension. It will manage your private keys and known pubkeys safely.
3. Go to [a PolkadotJS web UI](https://polkadot.js.org/apps/?rpc=ws://127.0.0.1/ws:9945). (it's not the same thing as the browser extension)
- If using another port or address, change it accordingly in the left panel.
4. In the UI: developer > RPC call > author > rotateKeys() and copy the result in clipboard
5. In the UI: developer > extrinsics > YOUR_SMITH_ACCOUNT > smithMembership > requestMembership(metadata)
- add your p2p endpoint (optional)
- add your session keys
- send the query
6. Wait 48h to ensure your node keeps sync (**both** best **and** finalized block numbers must increase every 6s)
7. Await at least 3 smith certifications. Members of the smith WoT can certify you with this extrinsic:
- In the UI: developer > extrinsics > CERTIFIER_SMITH_ACCOUNT > smithCert > addCert(receiver)
- This is not automatic, you can ask for certs on the forum or the Matrix chatroom.
8. In the UI: developer > extrinsics > YOUR_SMITH_ACCOUNT > smithMembership > claimMembership(maybe_idty_id)
- maybe_idty_id can be left empty since your identity id will be infered from your account address.
All extrinsics can be sent while connected to any Duniter node, but the RPC calls need a direct connection to your server. As some RPC calls should not be publicly callable for security reasons, the only ways to call them is from the server localhost or using an SSH bridge or other kind of secure tunnel.
rotateKeys can be called anytime you want. Then you have to call setSessionKeys with the new keys.
## Validate blocks (blacksmith work)
Once all the previous steps are completed, you can start to actually author blocks.
In the UI: developer > extrinsics > YOUR_SMITH_ACCOUNT > authorityMembers > goOnline()
If you're not able to monitor, reboot, act on your node, goOffline() to avoid penalty to the blockchain and to you. It will take effect after 2h, so please do it in advance if you plan to disconnect your server soon. goOnline can always be called after this, but after 100 days without authoring blocks you will loose your smith membership.
## Upgrade your node with minimal interruption
1. Modify docker image tag on your compose file
2. Run `docker compose pull`, this will pull the new image.
3. Run `docker compose up -d --remove-orphans`, this will recreate the container
4. Verify that your node restarted well `docker compose logs duniter-validator`
5. Remove the old image `docker rmi duniter/duniter-v2s:OLD_TAG`
xtask/res/templates/runtime-calls-category.md
+ 13
− 4
View file @ 582a46c2
There are **{{ calls_counter }}** {{ category_name }} calls from **{{ pallets | length }}** pallets.
{% for pallet in pallets -%}
### {{ pallet.name }} - {{ pallet.index }}
## {{ pallet.name }} - {{ pallet.index }}
{% for call in pallet.calls -%}
#### {{ call.name }} - {{ call.index }}
### {{ call.name }} - {{ call.index }}
<details><summary><code>{{ call.name }}(
{%- for param in call.params -%}
......@@ -23,8 +25,15 @@ Taking {{ call.weight }} % of a block.
```
</details>
{# replace markdown sytax in documentation breaking the final result #}
{{ call.documentation | replace(from="# WARNING:", to="WARNING:") | replace(from="## Complexity", to="**Complexity**") }}
{# lower heading title to integrate into document hierarchy #}
{# with a maximum to 6 #}
{{ call.documentation
| replace(from="# ", to="## ")
| replace(from="# ", to="## ")
| replace(from="# ", to="## ")
| replace(from="# ", to="## ")
| replace(from="####### ", to="###### ")
}}
{% endfor -%}
{% endfor -%}
xtask/res/templates/runtime-calls.md
+ 4
− 20
View file @ 582a46c2
......@@ -10,25 +10,9 @@ through on-chain governance mechanisms.
(usually automatically by the node).
1. **Disabled calls**: These calls can not be called directly, they are reserved for internal use by other runtime calls.
We only document user calls below.
{% set pallets = user_calls_pallets -%}
{% set calls_counter = user_calls_counter -%}
{% set category_name = "user" -%}
## User calls
{% include "runtime-calls-category.md" %}
{% set pallets = root_calls_pallets -%}
{% set calls_counter = root_calls_counter -%}
{% set category_name = "root" -%}
## Root calls
{% include "runtime-calls-category.md" %}
{% set pallets = disabled_calls_pallets %}
{% set calls_counter = disabled_calls_counter %}
{% set category_name = "disabled" %}
## Disabled calls
{% include "runtime-calls-category.md" -%}
xtask/src/gen_doc.rs
+ 38
− 61
View file @ 582a46c2
......@@ -194,56 +194,68 @@ impl From<&scale_info::Variant<PortableForm>> for ErroR {
}
}
// classify calls into categories depending on their origin
enum CallCategory {
// calls filtered by runtime
Disabled,
// inherents
Inherent,
OtherOrigin,
// ensure_root
Root,
// sudo
Sudo,
// user calls
User,
// other (like a certain proportion of technical comittee)
OtherOrigin,
}
impl CallCategory {
fn is(pallet_name: &str, call_name: &str) -> Self {
match (pallet_name, call_name) {
("System", "remark" | "remark_with_event") => Self::Disabled,
// substrate "system"
("System", _) => Self::Root,
("Babe", "report_equivocation_unsigned") => Self::Inherent,
("Scheduler", _) => Self::Root,
("Babe", "report_equivocation" | "report_equivocation_unsigned") => Self::Inherent,
("Babe", "plan_config_change") => Self::Root,
("Timestamp", _) => Self::Inherent,
("Balances", "set_balance" | "force_transfer" | "force_unreserve") => Self::Root,
("AuthorityMembers", "prune_account_id_of" | "remove_member") => Self::Root,
("Authorship", _) => Self::Inherent,
("Session", _) => Self::Disabled,
("Grandpa", "report_equivocation_unsigned") => Self::Inherent,
("Grandpa", "report_equivocation" | "report_equivocation_unsigned") => Self::Inherent,
("Grandpa", "note_stalled") => Self::Root,
("UpgradeOrigin", "dispatch_as_root") => Self::OtherOrigin,
("Timestamp", _) => Self::Inherent,
("ImOnline", _) => Self::Inherent,
("Sudo", _) => Self::Sudo,
// substrate "common"
(
"Identity",
"remove_identity" | "prune_item_identities_names" | "prune_item_identity_index_of",
"Balances",
"force_set_balance"
| "force_transfer"
| "force_unreserve"
| "force_adjust_total_issuance",
) => Self::Root,
("Cert", "del_cert" | "remove_all_certs_received_by") => Self::Root,
("SmithCert", "del_cert" | "remove_all_certs_received_by") => Self::Root,
("TechnicalCommittee", "set_members" | "disapprove_proposal") => Self::Root,
("Utility", "dispatch_as") => Self::Root,
("Sudo", _) => Self::Sudo,
("Treasury", "approve_proposal" | "reject_proposal") => Self::OtherOrigin,
("Utility", "dispatch_as" | "with_weight") => Self::Root,
// duniter
("Distance", "force_update_evaluation" | "force_valid_distance_status") => Self::Root,
("Distance", "update_evaluation") => Self::Inherent,
("AuthorityMembers", "remove_member_from_blacklist" | "remove_member") => Self::Root,
("UpgradeOrigin", "dispatch_as_root" | "dispatch_as_root_unchecked_weight") => {
Self::OtherOrigin
}
("Identity", "remove_identity" | "prune_item_identities_names" | "fix_sufficients") => {
Self::Root
}
("Certification", "del_cert" | "remove_all_certs_received_by") => Self::Root,
("TechnicalCommittee", "set_members" | "disapprove_proposal") => Self::Root,
// if not classified, consider it at a user call
_ => Self::User,
}
}
fn is_root(pallet_name: &str, call_name: &str) -> bool {
matches!(Self::is(pallet_name, call_name), Self::Root)
}
// only user calls
fn is_user(pallet_name: &str, call_name: &str) -> bool {
matches!(Self::is(pallet_name, call_name), Self::User)
}
fn is_disabled(pallet_name: &str, call_name: &str) -> bool {
matches!(Self::is(pallet_name, call_name), Self::Disabled)
}
}
/// generate runtime calls documentation
......@@ -477,6 +489,7 @@ fn get_weights(max_weight: u128) -> Result<HashMap<String, HashMap<String, Weigh
/// use template to render markdown file with runtime calls documentation
fn print_runtime(pallets: RuntimePallets) -> (String, String, String, String) {
// init variables
// -- user calls
let mut user_calls_counter = 0;
let user_calls_pallets: RuntimePallets = pallets
.iter()
......@@ -494,46 +507,14 @@ fn print_runtime(pallets: RuntimePallets) -> (String, String, String, String) {
}
})
.collect();
let mut root_calls_counter = 0;
let root_calls_pallets: RuntimePallets = pallets
.iter()
.cloned()
.filter_map(|mut pallet| {
let pallet_name = pallet.name.clone();
pallet
.calls
.retain(|call| CallCategory::is_root(&pallet_name, &call.name));
if pallet.calls.is_empty() {
None
} else {
root_calls_counter += pallet.calls.len();
Some(pallet)
}
})
.collect();
let mut disabled_calls_counter = 0;
let disabled_calls_pallets: RuntimePallets = pallets
.iter()
.cloned()
.filter_map(|mut pallet| {
let pallet_name = pallet.name.clone();
pallet
.calls
.retain(|call| CallCategory::is_disabled(&pallet_name, &call.name));
if pallet.calls.is_empty() {
None
} else {
disabled_calls_counter += pallet.calls.len();
Some(pallet)
}
})
.collect();
// event counter
let mut event_counter = 0;
pallets
.iter()
.for_each(|pallet| event_counter += pallet.events.len());
// error counter
let mut error_counter = 0;
pallets
.iter()
......@@ -552,10 +533,6 @@ fn print_runtime(pallets: RuntimePallets) -> (String, String, String, String) {
let mut context = tera::Context::new();
context.insert("user_calls_counter", &user_calls_counter);
context.insert("user_calls_pallets", &user_calls_pallets);
context.insert("root_calls_counter", &root_calls_counter);
context.insert("root_calls_pallets", &root_calls_pallets);
context.insert("disabled_calls_counter", &disabled_calls_counter);
context.insert("disabled_calls_pallets", &disabled_calls_pallets);
let call_doc = tera
.render("runtime-calls.md", &context)
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment