Skip to content

'Permissions' update #503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

'Permissions' update #503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions src/guide/blockchain/metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
35 changes: 21 additions & 14 deletions src/guide/blockchain/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this sentence in progress?


## Permission Tokens

Having a permission to do something means having a `PermissionToken` to do
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Having a permission to do something means having a `PermissionToken` to do
Having a permission to do something means having the corresponding `PermissionToken` to do

so. There are two ways for users to receive permission tokens: they can be
Expand All @@ -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
Expand Down Expand Up @@ -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)

Expand All @@ -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.

<!-- TODO: add more info about roles -->
<!-- TODO: add more info about roles; default roles? -->

### 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:
Expand All @@ -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:

Expand Down
45 changes: 26 additions & 19 deletions src/reference/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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
Expand All @@ -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();
```
```
Loading