diff --git a/src/guide/blockchain/metadata.md b/src/guide/blockchain/metadata.md index ba432d3b..51bb8b66 100644 --- a/src/guide/blockchain/metadata.md +++ b/src/guide/blockchain/metadata.md @@ -158,5 +158,9 @@ You can get the key value of an object metadata using ## Permissions -Pre-configured tokens in Iroha 2 that allow to set or remove -key-values in accounts, assets, asset definitions, and so on are described in [`Permissions`](/reference/permissions.md). +Permissions are tokens that allow accounts to set or remove key-values in Accounts, Assets, Asset Definitions, etc. + +For more information on permissions, see the following topics: + +- [Blockchain > Permissions](permissions.md): Detailed overview of what permissions are and how they operate. +- [Reference > Permissions](/reference/permissions.md): List of all preconfigured permission tokens and an example of granting a permission. diff --git a/src/guide/blockchain/permissions.md b/src/guide/blockchain/permissions.md index f2195ccb..33b1496f 100644 --- a/src/guide/blockchain/permissions.md +++ b/src/guide/blockchain/permissions.md @@ -1,13 +1,20 @@ # Permissions -Accounts need permission tokens for various actions on a blockchain, e.g. -to mint or burn assets. +For a user to be able to perform an action on the blockchain (e.g., minting and burning assets, registering domains, etc.), their account needs a permission—`PermissionToken`—to do that action. -There is a difference between a public and a private blockchain in terms of -permissions granted to users. In a public blockchain, most accounts have -the same set of permissions. In a private blockchain, most accounts are -assumed not to be able to do anything outside of their own account or -domain unless explicitly granted said permission. +::: info + +There is a difference between public and private blockchains in terms of permissions granted to users. In a public blockchain, most accounts have the same set of permissions. Whereas, in a private blockchain, most accounts are assumed to not be able to do anything outside of their own account or domain unless they are explicitly granted a specific permission. + +For more details, see [Public and Private Blockchains](../configure/modes.md). + +::: + +## Permission Tokens + +Technically, every `PermissionToken` + +## Permission Tokens Having a permission to do something means having a `PermissionToken` to do so. There are two ways for users to receive permission tokens: they can be @@ -16,8 +23,6 @@ set of permission tokens). Permissions are granted via `Grant` special instruction. Permission tokens and roles do not expire, they can only be removed using `Revoke` instruction. -## Permission Tokens - Permission token definitions have parameters. When a new permission token is registered, the names of the parameters and their types are checked against their names and types in the token definition. The token @@ -59,9 +64,11 @@ Here are some examples of parameters used for various permission tokens: epoch in milliseconds (more details about [time in Rust](https://doc.rust-lang.org/std/time/struct.SystemTime.html)). -### Pre-configured Permission Tokens +### Preconfigured Permission Tokens + +Iroha 2 also provides a number of _preconfigured_ permission tokens that can be granted -You can find the list of pre-configured permission tokens in the [Reference](/reference/permissions) chapter. +For the list of all preconfigured permission tokens, see [Reference > Permissions](/reference/permissions.md). ## Permission Groups (Roles) @@ -71,9 +78,9 @@ roles can be granted using the `Grant` instruction and revoked using the Before granting a role to an account, the role should be registered first. - + -### Register a new role +### Register a New Role Let's register a new role that, when granted, will allow another account access to the [metadata](/guide/blockchain/metadata.md) in Mouse's account: @@ -86,7 +93,7 @@ let role = iroha_data_model::role::Role::new(role_id) let register_role = RegisterBox::new(role); ``` -### Grant a role +### Grant a Role After the role is registered, Mouse can grant it to Alice: diff --git a/src/reference/permissions.md b/src/reference/permissions.md index d58aff61..ebe3a39a 100644 --- a/src/reference/permissions.md +++ b/src/reference/permissions.md @@ -4,17 +4,23 @@ This section provides details about pre-configured permission tokens in Iroha 2. ## Permission Tokens -The following permission tokens are pre-configured in Iroha 2: +::: tip Note -| Permission Token | Category | Operation | +A permission token can only grant a user's account the ability to perform an operation in relation to the Subject that the token is registered with. + +e.g., ??? + +::: + +| Permission Token | Subject | Operation | |-----------------------------------------|------------------|--------------------------------------------------------------------| -| [`CanUnregisterDomain`] | Domain | Allows to unregister a domain | -| [`CanSetKeyValueInDomain`] | Domain | Allows to add domain's metadata key value | -| [`CanRemoveKeyValueInDomain`] | Domain | Allows to remove domain's metadata key value | -| [`CanUnregisterAccount`] | Account | Allows to unregister an account | -| [`CanMintUserPublicKeys`] | Account | Allows to add a public key to an account | -| [`CanBurnUserPublicKeys`] | Account | Allows to remove a public key from an account | -| [`CanMintUserSignatureCheckConditions`] | Account | Allows to set check conditions for a signature | +| [`CanUnregisterDomain`] | Domain | Allows the user to unregister the Domain. | +| [`CanSetKeyValueInDomain`] | Domain | Allows the user to add metadata key-values to the Domain. | +| [`CanRemoveKeyValueInDomain`] | Domain | Allows the user to remove metadata key-values from the Domain. | +| [`CanUnregisterAccount`] | Account | Allows the user to unregister the Account. | +| [`CanMintUserPublicKeys`] | Account | Allows the user to add a public key to the Account. | +| [`CanBurnUserPublicKeys`] | Account | Allows the user to remove a public key from the Account. | +| [`CanMintUserSignatureCheckConditions`] | Account | Allows the user to set check conditions for a signature | | [`CanSetKeyValueInUserAccount`] | Account | Allows to add user's metadata key value | | [`CanRemoveKeyValueInUserAccount`] | Account | Allows to remove user's metadata key value | | [`CanRegisterAssetsWithDefinition`] | Asset | Allows to register a new asset with this definition | @@ -34,23 +40,24 @@ The following permission tokens are pre-configured in Iroha 2: ::: info The way permissions work in Iroha 2 is subject to change. -Only an owner of the subject can grant permissions for the subject. +Only the owner of a subject can grant users permissions to perform operations with that subject. -By default, all assets and accounts defined in the genesis block configuration file are created by `genesis@genesis` account. +By default, all assets and accounts defined in the genesis block configuration file are created by `genesis@genesis` account. This means that `alice@wonderland` is not the owner of `rose#wonderland` and cannot grant permission for `rose#wonderland`. -To avoid this you can: -1. Edit the `genesis.json` file to only include the creation of `alice@wonderland`, and then redeploy Iroha 2. -2. Create a subject (e.g., an asset definition) on behalf of `alice@wonderland`, and then give another account the permission to manage this subject. +To avoid this, you can do one of the following: +- Edit the `genesis.json` file so that it only includes the creation of `alice@wonderland`, then redeploy Iroha 2. +- Create a subject (e.g., an asset definition) on behalf of `alice@wonderland`, and then give another account the permission to manage this subject. ::: -### `General example` +## Granting Permission Tokens With this example, the owner-account can give permission for its subject to another account. -The example is based on the following pre-conditions: - The subject is created by the owner-account - The recipient account is created + +The example is based on the following preconditions: +- The subject is created by the owner-account. +- The recipient account is created. ```rust // Define the asset definition owner @@ -68,4 +75,4 @@ let can_mint_asset_with_definition_token = PermissionToken::new( let permission_expression = GrantExpr::new(can_mint_asset_with_definition_token, recipients_account); // Submit the transaction with the permission expression iroha_client.submit_blocking(permission_expression).unwrap(); -``` \ No newline at end of file +```