From 78efa7965d5b66f3cc4682c09ca378f6aab9048a Mon Sep 17 00:00:00 2001 From: weichweich Date: Tue, 14 Dec 2021 10:15:50 +0100 Subject: [PATCH] doc: remove old doc --- {docs => .maintain}/media/kilt.png | Bin README.md | 6 +- docs/kilt-pallets-description.md | 232 ----------------------------- docs/kilt-substrate.md | 85 ----------- 4 files changed, 2 insertions(+), 321 deletions(-) rename {docs => .maintain}/media/kilt.png (100%) delete mode 100644 docs/kilt-pallets-description.md delete mode 100644 docs/kilt-substrate.md diff --git a/docs/media/kilt.png b/.maintain/media/kilt.png similarity index 100% rename from docs/media/kilt.png rename to .maintain/media/kilt.png diff --git a/README.md b/README.md index 6742fb86a..dbc9f1936 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

- +

The KILT blockchain is the heart and soul behind KILT Protocol. @@ -10,6 +10,4 @@ It provides the immutable transaction ledger for the various KILT processes in t The nodes use Parity Substrate as the underlying blockchain technology stack, extended with our custom functionality for handling DIDs, CTypes, Attestations and Delegations. -* [The KILT developer documentation](https://dev.kilt.io) -* [Detailed explanation about KILT node module functionalities](./docs/kilt-pallets-description.md) -* [About KILT and Substrate in the Polkaverse](./docs/kilt-substrate.md) +## [The KILT developer documentation](https://dev.kilt.io) diff --git a/docs/kilt-pallets-description.md b/docs/kilt-pallets-description.md deleted file mode 100644 index b54e0d50b..000000000 --- a/docs/kilt-pallets-description.md +++ /dev/null @@ -1,232 +0,0 @@ -# Description of KILT Pallets - -Currently, the KILT runtime uses the following four custom pallets for handling the underlying KILT data structures: -* [`did`](../pallets/did) -* [`attestation`](../pallets/attestation) -* [`delegation`](../pallets/delegation) -* [`ctype`](../pallets/ctype) - -## The KILT DID Pallet - -The KILT blockchain node runtime defines a DID module exposing: - -### Add a DID - -```rust -fn add(origin, sign_key: T::PublicSigningKey, box_key: T::PublicBoxKey, doc_ref: Option>) -> DispatchResult -``` - -This transaction takes the following parameters: - -- `origin`: The public [ss58]() address of the caller of the method. -- `sign_key`: The [ed25519](http://ed25519.cr.yp.to/) or [sr25519](https://wiki.polkadot.network/docs/en/learn-cryptography) public signing key of the owner. -- `box_key`: The [x25519-xsalsa20-poly1305](http://nacl.cr.yp.to/valid.html) public encryption key of the owner. -- `doc_ref`: An optional u8 byte vector representing the reference (URL) to the DID document. - -The blockchain node verifies the transaction signature corresponding to the owner and inserts it to the blockchain storage by using a map (done by the substrate framework): - -```rust -struct DidRecord { - sign_key: T::PublicSigningKey, - box_key: T::PublicBoxKey, - doc_ref: Option> -} - -type DidStorage = StorageMap>> -``` - -### Remove a DID - -```rust -fn remove(origin) -> DispatchResult -``` - -This function takes the owner as a single parameter removes the DID from the storage map. -Thus, any any later read operation call does not return the data of a removed DID. - -## The KILT CType Pallet - -The KILT blockchain node runtime defines a CType module exposing - -```rust -fn add(origin, hash: T::Hash) -> DispatchResult -``` - -This function takes following parameters: - -- `origin`: The public [ss58](https://substrate.dev/docs/en/knowledgebase/advanced/ss58-address-format) address of the caller of the method -- `hash`: The CType hash as a [blake2b](https://blake2.net/) string - -The blockchain node verifies the transaction signature corresponding to the creator and -inserts it to the blockchain storage by using a map (done by the substrate framework): - -```rust -type CTypeStorage = StorageMap> -``` - -## The KILT Attestation Pallet - -The KILT blockchain node runtime defines an Attestation module exposing functions to - -- add a (delegated) attestation `add` -- revoke a (delegated) attestation `revoke` -- lookup an attestation `get(attestation)` -- lookup a delegated attestation `get(delegated_attestations)` - -on chain. - -### Add an Attestation - -```rust -fn add(origin, claim_hash: T::Hash, ctype_hash: T::Hash, delegation_id: Option) -> DispatchResult -``` - -The `add` function takes following parameters: - -- `origin`: The caller of the method, i.e. the public address ([ss58](https://substrate.dev/docs/en/knowledgebase/advanced/ss58-address-format)) of the (delegated) Attester. -- `claim_hash`: The Claim hash as [blake2b](https://blake2.net/) string used as the key of the entry. -- `ctype_hash`: The [blake2b](https://blake2.net/) hash of CType used when creating the Claim. -- `delegation_id`: An optional reference to a Delegation which this attestation is based on. - -The node verifies the transaction signature and inserts it to the state, if the provided attester -didn’t already attest the provided claimHash. -The attestation is stored by using a map: - -```rust -struct Attestation { - ctype_hash: T::Hash, - attester: T::AccountId, - delegation_id: Option, - revoked: bool, -} - -type AttestationStorage = StorageMap>> -``` - -Delegated Attestations are stored in an additional map: - -```rust -type DelegatedAttestationStorage = StorageMap> -``` - -### Revoke an Attestation - -```rust -fn revoke(origin, claim_hash: T::Hash, max_depth: u32) -> DispatchResult -``` - -- `origin`: The caller of the method, i.e. the public address ([ss58](https://substrate.dev/docs/en/knowledgebase/advanced/ss58-address-format)) of the (delegated) Attester. -- `claim_hash`: The Claim hash as [blake2b](https://blake2.net/) string used as the key of the entry. -- `max_depth`: The maximum number of parent checks of the Delegation which are supported in this call until finding the owner of the Delegation (or the Root) and ensuring that this is the address of the `origin`. Due to the recursive structure of checking for Delegations, this kind of limit is required for calculating the transaction fees and the weight of the transaction. - -The `revoke` function takes the claim hash (which is the key to lookup an attestation) as argument. -After looking up the attestation and checking the invoker's permissions, the revoked flag is set to true and the updated attestation is stored on chain. - -## The KILT Delegation Pallet - -The KILT blockchain node runtime defines a Delegation module exposing functions to - -- create a root delegation `create_root` -- add a delegation `add_delegation` -- revoke a delegation `revoke_delegation` -- revoke a whole hierarchy `revoke_root` -- lookup a root `get(root)` -- lookup a delegation `get(delegation)` -- lookup children of a delegation `get(children)` - -on chain. - -### Create a Root Delegation - -```rust -fn create_root(origin, root_id: T::DelegationNodeId, ctype_hash: T::Hash) -> DispatchResult -``` - -The `create_root` function takes the following parameters: - -- `origin`: The caller of the method, i.e., public address (ss58) of the owner of the trust hierarchy. -- `root_id`: A V4 UUID identifying the trust hierarchy. -- `ctype_hash`: The [blake2b](https://blake2.net/) hash of the CType this trust hierarchy is associated with. - -The node verifies the transaction signature and inserts it to the state. -The root is stored by using a map: - -```rust -struct DelegationRoot { - ctype_hash: T::Hash, - owner: T::AccountId, - revoked: bool, -} -type RootStorage = StorageMap>> -``` - -### Add a Delegation - -```rust -fn add_delegation( - origin, - delegation_id: T::DelegationNodeId, - root_id: T::DelegationNodeId, - parent_id: Option, - delegate: T::AccountId, - permissions: Permissions, - delegate_signature: T::Signature -) -> DispatchResult -``` - -The `add_delegation` function takes the following parameters: - -- `origin`: The caller of the method, i.e. the public address (ss58) of the Delegator. -- `delegation_id`: A V4 UUID identifying this delegation. -- `root_id`: A V4 UUID identifying the associated trust hierarchy. -- `parent_id`: An Optional V4 UUID identifying the parent delegation this delegation is based on. -- `delegate`: The public address (ss58) of the Delegate (ID receiving the delegation). -- `permissions`: The permission bit set (having `0001` for attesting permission and `0010` for delegation permission) -- `delegate_signature`: An `ed25519` or `sr25519` based signature by the delegate based on the `delegationId`, `rootId`, `parentId` and `permissions`. - -The node verifies the transaction signature and the delegate signature as well as all other data -to be valid and the delegator to be permitted and then inserts it to the state. The delegation is -stored by using a map: - -```rust -struct DelegationNode { - root_id: T::DelegationNodeId, - parent: Option, - owner: T::AccountId, - permissions: Permissions, - revoked: bool, -} -type DelegationsStorage = StorageMap>> -``` - -Additionally, if the delegation has a parent delegation, the information about the children of its -parent is updated in the following map that relates parents to their children: - -```rust -type ChildrenStorage = StorageMap> -``` - -### Revoke a DelegationRoot - -```rust -fn revoke_root(origin, root_id: T::DelegationNodeId, max_children: u32) -> DispatchResultWithPostInfo { -``` - -The `revoke_root` function takes the following parameters: - -- `origin`: The caller of the method, i.e. the public address (ss58) of the Delegator. -- `root_id`: A V4 UUID identifying the associated trust hierarchy. -- `max_children`: The maximum number of children of the Delegation root which can be revoked with this call. Due to the recursive structure of checking for Children, this kind of limit is required for calculating the transaction fees and the weight of the transaction. - -### Revoke a Delegation - -```rust -fn revoke_delegation(origin, delegation_id: T::DelegationNodeId, max_depth: u32, max_revocations: u32) -> DispatchResultWithPostInfo { -``` - -The `revoke_delegation` function takes the following parameters: - -- `origin`: The caller of the method, i.e. the public address (ss58) of the Delegator. -- `delegation_id`: A V4 UUID identifying this delegation. -- `max_depth`: The maximum number of parent checks of the Delegation which are supported in this call until finding the owner of the Delegation (or the Root) and ensuring that this is the address of the `origin`. Due to the recursive structure of checking for Delegations, this kind of limit is required (at least) for benchmarks. -- `max_revocations`: The maximum number of children of this Delegation node which can be revoked with this call. Due to the recursive structure of checking for Children, this kind of limit is required for calculating the transaction fees and the weight of the transaction. \ No newline at end of file diff --git a/docs/kilt-substrate.md b/docs/kilt-substrate.md deleted file mode 100644 index 02dd0d450..000000000 --- a/docs/kilt-substrate.md +++ /dev/null @@ -1,85 +0,0 @@ -# Building on the Parity Substrate Blockchain Framework - -During our first whiteboard phase, we were thinking about developing the KILT Protocol on -Ethereum smart-contracts, but we realized that we would have less **freedom of setting transaction costs**, while incurring a high level of overhead. -Instead, we started our -development on [Parity Substrate](https://www.parity.io/substrate/), a general blockchain framework, and built up the KILT blockchain from scratch based on its module library and core functionality. - -Building our blockchain on Parity Substrate has multiple advantages. Substrate has a very -good fundamental [architecture](https://substrate.dev/docs/en/knowledgebase/runtime/) and [codebase](https://github.com/paritytech/substrate) created by blockchain experts. -Moreover, the Substrate framework is developed in **Rust**, a memory efficient and fast compiled system programming -language, which provides a secure environment with virtually no runtime errors. -Additionally, the node runtime is also compiled to **WebAssembly**, so older version native nodes can always run the latest version node runtime in a WebAssembly virtual machine to **bypass the problem of a blockchain fork**. -Importantly, there is a vibrant developer community and rich [documentation](https://substrate.dev/). - -Our implementation is based on the [substrate-node-template](https://github.com/substrate-developer-hub/substrate-node-template) library (skeleton template for quickly building a Substrate based Blockchain), which is linked to the main Substrate codebase. - -## Helpful links - -* [Polkadot Wiki Glossary](https://wiki.polkadot.network/docs/en/glossary) -* [Substrate Tutorials](https://substrate.dev/en/tutorials) -* [Substrate Documentation](https://substrate.dev/) -* [Substrate JSON-RPC API](https://polkadot.js.org/docs/substrate/rpc) -* [Substrate Reference Rust Docs](https://substrate.dev/rustdocs/v3.0.0/sc_service/index.html) -* [Substrate Recipes](https://substrate.dev/recipes/introduction.html) -* [Awesome Substrate - Collection of Substrate Tooling](https://substrate.dev/awesome-substrate/) -* [Substrate Playground](https://playground.substrate.dev/) - -### Substrate Repositories - -* [Substrate Repository](https://github.com/paritytech/substrate) -* [Polkadot Repository](https://github.com/paritytech/polkadot) -* [Cumulus Repository](https://github.com/paritytech/cumulus) - -## Remote Procedure Calls - -The Ethereum ecosystem highly leverages [JSON-RPC](https://www.jsonrpc.org/specification) where one can efficiently call methods and parameters directly on the blockchain node. -Based on good experiences, developers decided to use it in Substrate as well. -The [Polkadot API](https://polkadot.js.org/api/) helps with communicating with the JSON-RPC endpoint, and the clients and services never have to talk directly with the endpoint. - -## Blocktime - -The blocktime is currently set to [10 seconds](../runtimes/parachain/lib.rs#82), but this setting is subject to change based on further research. -We will consider what is affected by this parameter, and in the long term it will be fine-tuned to a setting that provides the best performance and user experience for the participants of the KILT network. - -## Extrinsics and Block Storage - -In Substrate, the blockchain transactions are abstracted away and are generalized as[extrinsics](https://docs.substrate.dev/docs/extrinsics) in the system. -They are called extrinsics since they can represent any piece of information that is regarded as input from “the outside world” (i.e. from users of the network) to the blockchain logic. -The blockchain transactions in KILT are implemented through these general extrinsics, that are signed by the originator of the transaction. -We use this framework to write the KILT Protocol specific data entries on the Substrate based KILT blockchain: DIDs, CTypes, Attestations and Delegations. -The processing of each of these entry types is handled by our custom Substrate modules called pallets. - -Under the current consensus algorithm, authority validator nodes (whose addresses are listed in the genesis block) can create new blocks. -These nodes [validate](https://substrate.dev/docs/en/knowledgebase/learn-substrate/tx-pool#transaction-lifecycle) incoming transactions, put them into the pool, and include them in a new block. -While creating the block, the node executes the transactions and stores the resulting state changes in its local storage. -Note that the size of the entry depends on the number of arguments the transaction/respective extrinsic method has. -The size of the block is hence dynamic and will depend on the number and type of transactions included in the new block. -The valid new blocks are propagated through the network and other nodes execute these blocks to update their local state (storage). - -## Authoring & Consensus Algorithm - -We use [Aura](https://wiki.parity.io/Aura) as the authoring algorithm, since we are still in a permissioned blockchain mode. -We will probably move to another algorithm in the future (e.g. [BABE](https://w3f-research.readthedocs.io/en/latest/polkadot/BABE.html)). - -For consensus we use [GRANDPA](https://github.com/paritytech/substrate#2-description). - -At a later stage, we most likely will change to a different consensus algorithm that will incorporate additional features (e.g. proving availability of certain services) and we might leverage concepts from BABE+GRANDPA while designing this new consensus mechanism. - -## Polkadot Integration - -As a further great advantage, by basing ourselves on Substrate we can easily connect to the Polkadot ecosystem. -This could provide security for the KILT network by leveraging the global -consensus in the Polkadot network. -We are planning to integrate KILT into the [Polkadot](https://polkadot.network/) network. -It is fairly straightforward to achieve this by simply including specific Substrate modules into the KILT Collator node implementation. -The exact details of this integration is subject to future agreements between Polkadot and KILT and the technological development of Polkadot, Substrate and KILT. - -## KILT Tokens - -Coin transfers are implemented as a balance-based mechanism in Substrate. -In our testnet, every new identity gets 1000 KILT Tokens from a root entity in the system who is wired into the genesis block. -At a later stage, we are proposing to provide KILT Tokens for new developers wanting to join our test networks (testnet and Spirit-Net testnet) on a simple request-provide based mechanism. -Preferably, developers will be able to register on our website, and we manually transfer KILT tokens to the registered developers after vetting them. -Importantly, these test tokens will not be usable on our mainnet. -After the launch of the mainnet (Spirit-Net) and the public KILT Token sale, the tokens will be available on cryptocurrency exchanges. \ No newline at end of file