Auth descriptors and rules

An auth descriptor allows one or more key pairs to be used to log into an account.

• Account: This is an on-chain entity representing a user or an application on the blockchain. It can interact with other entities like tokens and smart contracts.
• User: A person seeking access to on-chain services through an account.
• Key pair: A cryptographic tool used for identification and authorization. It consists of a public key (shared publicly) and a private key (kept secret). The private key should never be shared.

Key points:

• User and key pair relationships:
  • A single user can have multiple key pairs for added security or convenience.
  • A single key pair should never be shared among multiple users.
• Account and key pair/user relationships:
  • A single account can be accessed by multiple keypairs and users, enabling shared accounts for groups or applications.
  • A single key pair can be used to access multiple accounts, providing flexibility for the user.

warning

Never share your private key. The FT4 library offers secure methods for managing multiple user access to accounts without compromising private keys.

Role of auth descriptors:

An auth descriptor defines the keypairs authorized to interact with the blockchain on behalf of an account. This allows for:

• Multi-signature Security: By requiring multiple keypairs to co-sign transactions, critical operations can be secured with the combined approval of authorized parties.
• Granular Access Control: Permissions specified in the descriptor can restrict the actions and resources specific keypairs can access within an account.

Auth descriptor

An auth descriptor has arguments and rules:

• The arguments include who can access it and what they can do.
• The rules explain under what conditions the auth descriptor is usable.

Auth descriptor arguments

Components:

1. Public keys: This component specifies the public keys that can be used to identify authorized key pairs for accessing the account. You can include multiple public keys to establish multi-signature access control.
2. Permissions (Flags): This component defines the specific actions or resources the authorized key pairs can access or interact with within the account. This allows for granular control over user privileges.
3. Required signatures: This component, optional for single-signature setups, specifies the number of authorized key pairs whose signatures are required for a transaction to be valid. This configuration enables multi-signature authentication, where multiple key pair approvals are needed for critical actions, enhancing security. This value can be less than the number of public keys provided if not all signers need to sign a transaction.

Variations:

• Single-signature (single-sig): If only one key pair can be granted access, the "Required Signatures" component can be omitted. This simplifies the auth descriptor for straightforward single-user scenarios.
• Multi-signature (multi-sig): The default configuration includes the "Required Signatures" component, enabling scenarios where multiple key pairs need to co-sign transactions, providing higher security for critical operations.

The Code examples section contains code examples illustrating the creation of auth descriptors.

Auth descriptor rules

Auth descriptor rules use a combination of operators, variables, and values to define specific conditions that must be met for an auth descriptor to be considered valid.

• Operators
  • >: Greater than
  • >=: Greater than or equal to
  • =: Equal to
  • <: Less than
  • <=: Less than or equal to
• Variables
  • operation_count: Represents the number of times the account has been used.
  • block_time: Represents the timestamp of the latest block on the blockchain.
  • block_height: Represents the block height of the latest block on the blockchain.
  • relative_block_height: Same as block_height, but the value is relative to the block in which the auth descriptor was registered instead of the genesis block.
  • relative_block_time: Same as block_time but relative to the block in which the auth descriptor was registered instead of the timestamp of the genesis block.

In the case of the two relative rules, an expression like relative_block_time < 120000 would mean that the the auth descriptor would be valid from its creation and 120000ms (aka 2 minutes) into the future.

note

The operation_count variable is only compatible with the <= and < operators.

A rule can either be simple or complex. Complex rules have multiple conditions, and they must all be true for the auth descriptor to be usable.

When considering whether an auth descriptor is usable, the rules will be checked, and the auth descriptor will be assigned a status. Based on the evaluation of its rules, an auth descriptor can be assigned one of three statuses:

• Active: The auth descriptor meets all its rule requirements and can be used for transactions.
• Inactive: The auth descriptor currently violates one or more rule conditions, but it may become usable if the conditions change.
• Expired: The auth descriptor permanently violates its rules and can no longer be used for transactions.

Expired auth descriptors will be automatically cleaned up when the user interacts with an account, and you do not need to remove them manually.

The Code examples section contains code examples illustrating auth descriptor rules.