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

refac doc homepage

parent 2bb3115e
No related branches found
No related tags found
1 merge request!306doc refac
Show whitespace changes
Inline Side-by-side
README.md
+ 25
− 184
View file @ cf894871
...@@ -20,35 +20,36 @@ Multiple documentation sources are available depending on the level of detail yo ...@@ -20,35 +20,36 @@ Multiple documentation sources are available depending on the level of detail yo
### Internal documentation TOC ### Internal documentation TOC
- [README](./README.md) - [README](./README.md) (this file)
- [Use](#use) - [Use](#use)
- [Test](#test)
- [Contribute](#contribute) - [Contribute](#contribute)
- [Structure](#project-structure) - [License](#license)
- [docker](./docker/) docker-related documentation - [docs](./docs/) internal documentation
- [docs](./docs/) - [api](./docs/api/) API
- [api](./docs/api/) - [manual](./docs/api/manual.md) manage account and identities
- [manual](./docs/api/manual.md)
- [runtime-calls](./docs/api/runtime-calls.md) the calls you can submit through the RPC API - [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-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 - [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) - [beginner-walkthrough](./docs/dev/beginner-walkthrough.md)
- [git-conventions](./docs/dev/git-conventions.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) - [launch-a-live-network](./docs/dev/launch-a-live-network.md)
- [setup](./docs/dev/setup.md) - [setup](./docs/dev/setup.md)
- [compilation features](./docs/dev/compilation.md) - [compilation features](./docs/dev/compilation.md)
- [verify-runtime-code](./docs/dev/verify-runtime-code.md) - [verify-runtime-code](./docs/dev/verify-runtime-code.md)
- [weights-benchmarking](./docs/dev/weights-benchmarking.md) - [weights-benchmarking](./docs/dev/weights-benchmarking.md)
- [upgrade-substrate](./docs/dev/upgrade-substrate.md) - [upgrade-substrate](./docs/dev/upgrade-substrate.md)
- [test](./docs/test/)
- [replay-block](./docs/test/replay-block.md) - [replay-block](./docs/test/replay-block.md)
- [user](./docs/user/) - [user](./docs/user/) user documentation
- [autocompletion](./docs/user/autocompletion.md) - [autocompletion](./docs/user/autocompletion.md)
- [debian installation](./docs/user/installation_debian.md) - [debian installation](./docs/user/installation_debian.md)
- [packaging](./docs/packaging/) - [distance](./docs/user/distance.md)
- [build-for-arm](./docs/packaging/build-for-arm.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 - [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 - [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 - [live-tests](./live-tests/) sanity checks to test the storage of a live chain
...@@ -58,23 +59,23 @@ Multiple documentation sources are available depending on the level of detail yo ...@@ -58,23 +59,23 @@ Multiple documentation sources are available depending on the level of detail yo
The easiest way is to use the docker image. 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
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 ### 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. 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
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 #### Control when your local blockchain should produce blocks
...@@ -85,34 +86,9 @@ You can decide when to produce blocks with the cli option `--sealing` which has ...@@ -85,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=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`). - `--sealing=manual`: produce a block upon receiving an RPC request (method `engine_createBlock`).
### Autocompletion ### Shell autocompletion
See [autocompletion](./docs/user/autocompletion.md).
## 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: See [autocompletion](./docs/user/autocompletion.md) to generate shell autocompletion for duniter commands.
```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
```
## Contribute ## Contribute
...@@ -139,20 +115,11 @@ cargo build ...@@ -139,20 +115,11 @@ cargo build
Use Rust's native `cargo` command to build and launch the node: Use Rust's native `cargo` command to build and launch the node:
```sh ```sh
cargo run -- --dev --tmp cargo run -- --dev
``` ```
This will deploy a local blockchain with test accounts (Alice, Bob, etc) in the genesis. This will deploy a local blockchain with test accounts (Alice, Bob, etc) in the genesis.
Open `https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944` to watch and interact with your node.
## 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.
Start the development chain with detailed logging: Start the development chain with detailed logging:
...@@ -160,138 +127,11 @@ Start the development chain with detailed logging: ...@@ -160,138 +127,11 @@ Start the development chain with detailed logging:
RUST_LOG=debug RUST_BACKTRACE=1 ./target/debug/duniter -lruntime=debug --dev RUST_LOG=debug RUST_BACKTRACE=1 ./target/debug/duniter -lruntime=debug --dev
``` ```
## Multi-Node Local Testnet ## License
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 See [LICENSE](./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
``` ```
## 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 CopyLeft 2021-2023 Axiom-Team
Some parts borrowed from Polkadot (Parity Technologies (UK) Ltd.) Some parts borrowed from Polkadot (Parity Technologies (UK) Ltd.)
...@@ -307,3 +147,4 @@ GNU Affero General Public License for more details. ...@@ -307,3 +147,4 @@ GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License 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/>. along with Duniter-v2S. If not, see <https://www.gnu.org/licenses/>.
```
docker-compose.yml
+ 1
− 1
View file @ cf894871
...@@ -5,7 +5,7 @@ services: ...@@ -5,7 +5,7 @@ services:
container_name: duniter-v2s-mirror container_name: duniter-v2s-mirror
# the image tells which network you are connecting to # the image tells which network you are connecting to
# here it is gdev network # here it is gdev network
image: duniter/duniter-v2s-gdev:latest image: duniter/duniter-v2s-gdev-800:latest
ports: ports:
# prometheus telemetry to monitor resource use # prometheus telemetry to monitor resource use
- 9615:9615 - 9615:9615
......
docker/compose/docker-compose.smith.yml
+ 1
− 1
View file @ cf894871
...@@ -4,7 +4,7 @@ services: ...@@ -4,7 +4,7 @@ services:
# duniter smith node # duniter smith node
duniter-v2s-smith: duniter-v2s-smith:
container_name: duniter-v2s-smith container_name: duniter-v2s-smith
image: duniter/duniter-v2s-gdev:latest image: duniter/duniter-v2s-gdev-800:latest
ports: ports:
# RPC API of a smith node should not be exposed publicly! # RPC API of a smith node should not be exposed publicly!
- 127.0.0.1:9944:9944 - 127.0.0.1:9944:9944
......
docs/api/manual.md
+ 15
− 13
View file @ cf894871
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
This functional documentation presents how wallets can interact with the blockchain. 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. 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 ## Notations
...@@ -11,26 +11,27 @@ Only ĞDev is covered for now. ...@@ -11,26 +11,27 @@ Only ĞDev is covered for now.
## Account existence ## 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 ## 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. 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. 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. 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. 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. The distance evaluation must be requested for the pending identity using `distance.requestDistanceEvaluation`.
1. 3 sessions later, if the distance rule is respected, `identity.validateIdentity` can be called. 1. 3 distance sessions later, if the distance rule is respected, identity is validated automatically.
## Change key ## 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: 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 new owner key payload prefix (rust definition: `b"icok"`)
* The identity index (rust type `u64`) - the genesis block hash. (rust type `[u8; 32]` (`H256`))
* The old key (rust type `u64`) - The identity index (rust type `u64`)
- The old key (rust type `u64`)
This payload must be signed with the new key. 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 ...@@ -43,9 +44,10 @@ This feature is useful in case the user has lost their private key since the rev
### Generate the revocation payload ### Generate the revocation payload
The revocation needs this SCALE encoded (see SCALE encoding section below) 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 revocation payload prefix (rust definition: `b"revo"`)
* the genesis block hash. (rust type `[u8; 32]` (`H256`)) - 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. This payload must be signed with the corresponding revocation key.
......
docs/test/replay-block.md → docs/dev/replay-block.md
+ 2
− 0
View file @ cf894871
# How to replay a block # 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. 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 1. Checkout the git tag of the runtime version at the block you want to replay
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment