diff --git a/README.md b/README.md index b6e13ab64a..7db305e299 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ For more information, see [creditcoin.org](https://creditcoin.org), or read the ## Getting Started -- [Miner Setup](./docs/miner-setup.md) - [Using PolkadotJs](./docs/using-polkadotjs.md) ## Developer Setup @@ -27,7 +26,7 @@ you terminate the process. After the project has been built, there are other way node. ```sh -cargo run --release -- --dev --tmp --mining-key +cargo run --release -- --dev --tmp ``` ### Explore Node Options @@ -92,7 +91,7 @@ Devnet bootnodes: This command will start the single-node development chain with persistent state: ```bash -./target/release/creditcoin-node --dev --mining-key +./target/release/creditcoin-node --dev ``` Purge the development chain's state: @@ -104,7 +103,7 @@ Purge the development chain's state: Start the development chain with detailed logging: ```bash -RUST_BACKTRACE=1 ./target/release/creditcoin-node -ldebug --dev --mining-key +RUST_BACKTRACE=1 ./target/release/creditcoin-node -ldebug --dev ``` ### Connect with Polkadot-JS Apps Front-end diff --git a/docs/dev-guide/src/architecture/client.md b/docs/dev-guide/src/architecture/client.md index 8792c4d6bd..48d6a40b5f 100644 --- a/docs/dev-guide/src/architecture/client.md +++ b/docs/dev-guide/src/architecture/client.md @@ -24,67 +24,22 @@ the client. This is where we put together all of the pieces of the client - configuring storage, kicking off networking, setting up the RPC server, connecting to telemetry, setting up the block import pipeline (and consensus, which is part of the import pipeline), and more. -This is also the entrypoint to mining (we just spawn a bunch of threads which are tasked with mining and submitting results). This code lives in [`node/src/service.rs`](https://github.com/gluwa/creditcoin/tree/dev/node/src/service.rs). ## RPC This is where we define custom RPC methods and extend the standard RPC server with our custom method handlers. -For example, we expose a custom RPC method for retrieving -your node's current hashrate so node operators can monitor their mining performance. The code for extending the RPC server with custom handlers lives in [`node/src/rpc.rs`](https://github.com/gluwa/creditcoin/tree/dev/node/src/rpc.rs). Once you've defined your custom RPC methods and their handlers, you would need to edit this code to register your new handlers. The code for _defining_ new RPC methods is currently located in [`node/rpc`](https://github.com/gluwa/creditcoin/tree/dev/node/rpc). -## Consensus / PoW +## Consensus / NPoS -The client also contains consensus-related code. Creditcoin uses Proof of Work, which requires block authors -to generate solutions to a problem (mining) and if a "good enough" solution is produced then a block can be authored. The majority of the actual -consensus is implemented in substrate, so the only parts we have to worry about are providing the difficulty, verifying -a given solution, and generating solutions (mining). +The client also contains consensus-related code. -### Difficulty +Creditcoin uses Nominated Proof of Stake (NPoS), a variation of the Proof of Stake (PoS) consensus algorithm. NPoS introduces a nominator-validator model where nominators can select and back validators. Nominators delegate their stake to validators, and in return, they can receive a portion of the validator's rewards. This system allows token holders, who may not have enough stake or technical expertise to become a validator, to nonetheless participate in the network and earn rewards by supporting trusted validators instead. Thereby, it promotes a more inclusive and secure network, as the nomination process enables a broader set of token holders to participate in consensus and governance than under a traditional PoS model. -The difficulty is actually determined in runtime logic, so on the client-side we use a runtime API to call into the runtime -logic and get the difficulty for the current block. More specifically, the difficulty adjustment and management occurs in the -difficulty pallet (detailed in the `runtime` section). - -### Verifying a Solution - -First to clarify, in our case the "problem" miners are solving is the following: - -```pseudocode -encode(arg) = SCALE encode arg to bytes -sha3(bytes) = calculate sha3 hash of the given bytes -concat(a, b,...) = concatenate a, b, ... - -// H256 is a 256-bit hash type, U256 is a 256-bit unsigned integer type - -def do_work(difficulty: U256, pre_hash: H256, nonce: H256) -> H256: - return sha3(concat(encode(difficulty), encode(pre_hash), encode(nonce))) - -def is_solution(work: H256, nonce: H256, difficulty: U256, pre_hash: H256) -> bool: - calculated = do_work(difficulty) - - // U256.MAX is the maximum value for an unsigned 256-bit integer, i.e. 2^256 - 1 - - return work == calculated and U256(work) * difficulty <= U256.MAX - -// choose a nonce such that is_solution(do_work(difficulty, pre_hash, nonce), nonce, difficulty, pre_hash) == True -``` - -Given a proposed solution, we consider it valid if - -1. The hash is correct (matches the value obtained by recalculating the hash from input data) -2. The product of the hash and difficulty do not overflow a 256-bit unsigned integer. In other words `hash * difficulty <= 2^256 - 1` - -This code lives in the [`sha3pow` crate](https://github.com/gluwa/creditcoin/tree/dev/sha3pow). - -### Generating Solutions (Mining) - -Mining comes down to essentially picking random nonce values until you find one with the correct properties. -Once we find an appropriate nonce, we submit the solution to a `MiningHandle` which then proceeds with verification and moving forward -with publishing the block. This occurs in [`service.rs`](https://github.com/gluwa/creditcoin/tree/dev/node/src/service.rs) in the `creditcoin-node` crate. +Read more about the Nominated Proof of Stake system in the [Creditcoin Docs](https://docs.creditcoin.org/staking). diff --git a/docs/dev-guide/src/architecture/runtime/pallet-difficulty.md b/docs/dev-guide/src/architecture/runtime/pallet-difficulty.md index f719550c2b..c5cec7ab52 100644 --- a/docs/dev-guide/src/architecture/runtime/pallet-difficulty.md +++ b/docs/dev-guide/src/architecture/runtime/pallet-difficulty.md @@ -1,4 +1,4 @@ # Difficulty Pallet -The difficulty pallet is responsible for storing the difficulty of the current block, and calculating the difficulty for the next block. -The fact that this logic lives in a pallet means that we canchange our difficulty adjustment algorithm with a runtime upgrade, which is cool. +The difficulty pallet is responsible for calculating and storing the difficulty for blocks produced using the old Proof of Work system. +The fact that this logic lives in a pallet means that could change our difficulty adjustment algorithm with a runtime upgrade, which is cool. diff --git a/docs/dev-guide/src/architecture/runtime/runtime.md b/docs/dev-guide/src/architecture/runtime/runtime.md index 2619fb454f..ae840ec2e3 100644 --- a/docs/dev-guide/src/architecture/runtime/runtime.md +++ b/docs/dev-guide/src/architecture/runtime/runtime.md @@ -41,9 +41,11 @@ These pallets are all part of substrate and aren't maintained by the creditcoin - [Balances](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html) - [FRAME System](https://paritytech.github.io/polkadot-sdk/master/frame_system/index.html) - [Scheduler](https://paritytech.github.io/polkadot-sdk/master/pallet_scheduler/index.html) +- [Staking](https://paritytech.github.io/polkadot-sdk/master/pallet_staking/index.html) - [Sudo](https://paritytech.github.io/polkadot-sdk/master/pallet_sudo/index.html) - [Timestamp](https://paritytech.github.io/polkadot-sdk/master/pallet_timestamp/index.html) - [Transaction Payment](https://paritytech.github.io/polkadot-sdk/master/pallet_transaction_payment/index.html) +- [Utility](https://paritytech.github.io/polkadot-sdk/master/pallet_utility/index.html) ### Internal Pallets diff --git a/docs/dev-guide/src/getting-started/observing-your-chain.md b/docs/dev-guide/src/getting-started/observing-your-chain.md index 94f92500db..a0fa4cc6dd 100644 --- a/docs/dev-guide/src/getting-started/observing-your-chain.md +++ b/docs/dev-guide/src/getting-started/observing-your-chain.md @@ -15,6 +15,6 @@ In the newly opened menu, expand the `Development` section at the bottom, then s Finally click the Switch button at the top of the chain selection menu: !["Switch"](../img/switch-chain.png) -The explorer should now show the chain running on your local node, and new blocks should be appearing regularly (every 5-30 seconds): +The explorer should now show the chain running on your local node, and new blocks should be appearing regularly (every 15 seconds): ![It should look something like this](../img/local-node-explorer.png) diff --git a/docs/dev-guide/src/getting-started/running-a-node.md b/docs/dev-guide/src/getting-started/running-a-node.md index 56140c8bb6..9972c2c211 100644 --- a/docs/dev-guide/src/getting-started/running-a-node.md +++ b/docs/dev-guide/src/getting-started/running-a-node.md @@ -5,7 +5,7 @@ Now that you've built a `creditcoin-node` from source, you can get a minimal development node running with: ```bash -./target/release/creditcoin-node --dev --mining-key 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY --mining-threads 1 +./target/release/creditcoin-node --dev ``` The node should start running and produce output similar to below: @@ -39,8 +39,8 @@ The node should start running and produce output similar to below: ``` By default this is a temporary chain, so when you stop your development node the chain will be wiped out. If you want a local development -chain that is persistent, you can use the `local` chain specification: +chain that is persistent, you can use the `--base-path` flag to specify a directory where the chain's data will be stored: ```bash -./target/release/creditcoin-node --chain local --validator --mining-key 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY --mining-threads 2 +./target/release/creditcoin-node --dev --base-path persistent-chain ``` diff --git a/docs/dev-guide/src/getting-started/substrate-resources.md b/docs/dev-guide/src/getting-started/substrate-resources.md index 3fe564f4dc..31c25ed9fc 100644 --- a/docs/dev-guide/src/getting-started/substrate-resources.md +++ b/docs/dev-guide/src/getting-started/substrate-resources.md @@ -1,7 +1,7 @@ # Learning about substrate The Creditcoin blockchain is built on the [substrate framework](https://docs.substrate.io/), which provides most of the underlying -blockchain functionality (P2P networking, block production, RPC server, storage, etc.). This allows us +blockchain functionality (P2P networking, block production, block finalizaiton, RPC server, storage, etc.). This allows us to focus on the functionality specific to creditcoin and additionally we benefit from existing tooling developed for the polkadot/substrate ecosystem (such as the polkadot explorer, polkadotJS, telemetry, etc.). @@ -12,6 +12,6 @@ all of the material in the [Learn section](https://docs.substrate.io/learn/). That should give you a rough understanding of substrate's architecture, and how the pieces fit together. -For learning about FRAME and best practices, the [substrate repository](https://github.com/paritytech/substrate) has a bunch of pallets of varying complexity that serve as good reference points. -For starters, the [sudo pallet](https://github.com/paritytech/substrate/tree/polkadot-v0.9.32/frame/sudo) is fairly small and +For learning about FRAME and best practices, the [substrate repository](https://github.com/gluwa/substrate) has a bunch of pallets of varying complexity that serve as good reference points. +For starters, the [sudo pallet](https://github.com/gluwa/substrate/tree/master/frame/sudo) is fairly small and digestible. diff --git a/docs/miner-setup.md b/docs/miner-setup.md deleted file mode 100644 index 0aec7bbfff..0000000000 --- a/docs/miner-setup.md +++ /dev/null @@ -1,78 +0,0 @@ -# Creditcoin Mining Node Setup - -## Prerequisites - -- Working [Docker](https://www.docker.com) installation - -**Notes:** - -For testing runtime upgrade/migrations Gluwa is using a 4 vCPU, 32 GiB RAM, -Memory optimized virtual machine in Azure. The size spec is `Standard_E4as_v4`. -See the `vmSize` parameter in -[.github/runner.bicep](https://github.com/gluwa/creditcoin/blob/dev/.github/runner.bicep) -for reference. - -## Setup Steps - -1) In order to receive mining rewards you will need an account on the Creditcoin network. Each account has an address and a balance associated with it. - The account is backed by a keypair. You can use an existing ECDSA keypair (e.g. from pre-Creditcoin 2.0) or you can generate a new keypair. - You can use [subkey](https://docs.substrate.io/v3/tools/subkey/) to retrieve the account address from an existing private key - (e.g. from pre-Creditcoin 2.0) or to generate a new keypair. - - - Using an existing ECDSA keypair: - - Your private key should be formatted as hex and start with `0x`, for example `0x3351b11eca7b5c78c0f55c681d9a2e8a0630bcc7a95a35a4a87615c916771774` - - Note: if your existing private key starts with `00`, remove the leading `00` first. - - Run `docker run -it docker.io/parity/subkey inspect --scheme Ecdsa ` which will display the account information fot the keypair. For example: - - ```bash - Secret Key URI `0x3351b11eca7b5c78c0f55c681d9a2e8a0630bcc7a95a35a4a87615c916771774` is account: - Secret seed: 0x3351b11eca7b5c78c0f55c681d9a2e8a0630bcc7a95a35a4a87615c916771774 - Public key (hex): 0x02abf7befd96f80ce3a27772e7903f45a930c54ede2f0b9e052bfb21e90e0a4b40 - Account ID: 0xe37a568057962e95990cbba46c68f8d5b0d0d614abc8bc9f4e46af3e7aa8880c - Public key (SS58): KW6p8XTkd6pLhTnwfSfr3hUcVSKTQhJHZxTVD8RrpfUhUTrvn - SS58 Address: 5HCy4x9b5mW28EYheGn14bWidQkhab5VMiNakia7i4VfxTKs - ``` - - - Copy the `SS58 Address` for later use - - Generate a new keypair - - Run `docker run -it docker.io/parity/subkey:latest generate`. This will generate a new keypair and print the account information, for example: - - ```bash - Secret phrase: toss frown run relief book lift aunt guard reduce shell genuine alarm - Network ID: substrate - Secret seed: 0x5ad92bddf82eae47f5c9cc77a749fd175d9d80aadeab6555e3126a087f5eb5f1 - Public key (hex): 0x03084078b5d3633f53ceb103199332aaf86e7ebc1b2975e697dd5dc8653692b7b9 - Account ID: 0x7bbf1daa8ccb9aedccade233879f299a5485fbd0922d9458b19a5dbfde71da3c - Public key (SS58): KW8u8Y1GgAGWtTfU5o92imPsYVkowfbsKE7hosQHwJ2E7gF9h - SS58 Address: 5ErxX8PgVYVE3WbCkSs9mvioFHVrsc4uXFwkF3G9Pyv4FC2w - ``` - - - Store your secret phrase (a 12-word mnemonic) in a secure location. We won’t use this phrase directly, but you’ll need it to access the account or recover your private key. - - Copy the `SS58 Address` for later use -2) Start mining node - - Make make sure that your port 30333 is accessible by external connections - - Obtain your public IP address - - Run (remove comment lines first) - - ```bash - - docker run -p 30333:30333 -v :/data gluwa/creditcoin:2.0.0-runtime-210 \ - # running a mining node - --validator \ - # (optional) REPLACE with a name for your node, to make it easier to identify - --name \ - # allow prometheus metrics to be scraped - --prometheus-external \ - # (optional) opt in to telemetry - --telemetry-url "wss://telemetry.polkadot.io/submit/ 0" "wss://telemetry.creditcoin.network/submit/ 0" \ - # node to connect to on boot, in order to join the network - --bootnodes "/dns4/bootnode.creditcoin.network/tcp/30333/p2p/12D3KooWAEgDL126EUFxFfdQKiUhmx3BJPdszQHu9PsYsLCuavhb" "/dns4/bootnode2.creditcoin.network/tcp/30333/p2p/12D3KooWSQye3uN3bZQRRC4oZbpiAZXkP2o5UZh6S8pqyh24bF3k" "/dns4/bootnode3.creditcoin.network/tcp/30333/p2p/12D3KooWFrsEZ2aSfiigAxs6ir2kU6en4BewotyCXPhrJ7T1AzjN" \ - # REPLACE with the public IP address or host name that your node can be reached at - --public-addr "/dns4//tcp/30333" \ - # we want to connect to the mainnet - --chain mainnet \ - # REPLACE with your mining public key/address to receive rewards at - --mining-key \ - # the port to use for node-to-node communication - --port 30333 - ```