Format of keyless addresses

Tech description of keyless addresses

IDs of keyless addresses

Regular blockchain addresses in TRAIT are represented as a string of 49 symbols. For example: ttqxHzRJmmjFBcE7Lb5Xs4GNMq2gFSt28JyvTEqjhqzE9EGP4. You use this string to check the balance or to specify a recipient of tokens.

In contract, keyless addresses can be referred in two ways:

• as a regular blockchain address - a string of 49 symbols;

• as a unique ID of keyless address;

These two formats are interchangeable. Having the keyless address in the string format - you can decode it and get unique ID of the address. Having the ID of the address - you can encode it into the blockchain address. This encoding/decoding can be done completely offline and without access to the live blockchain.

IDs of keyless addresses can be represented as follows:

• AppAgent keyless address:

  • type of the address - AppAgent address;

  • ID of the AppAgent - uint32;

• Transactional keyless address:

  • type of the address - Transactional address;

  • ID of the AppAgent - uint32;

  • ID of the Transactional address - uint32;

• Named keyless address:

  • type of the address - Named address;

  • ID of the AppAgent - uint32;

  • name of the address - 10 chars;

Depending on the needs you can use blockchain address or its ID in your app.

How to encode and decode keyless address

Encoding/decoding of keyless addresses is performed according to a well-defined cryptographic algorithm. Deviation from this algorithm will lead to incorrect results.

To encode/decode keyless addresses, it is recommended to use the library available in Rust, Python, TypeScript. The library can be found here.

Address format and construction

AppAgent Addresses

• Identifier: 1

• Format:

  • Bytes [0:3] - AppAgent ID

  • Byte 4 - Address Identifier

  • Bytes [5:31] - Checksum

• Purpose: Used to identify AppAgents within the system.

• Number of available addresses per AppAgent: One.

• Example Use Case: Managing app agent deposits, subscriptions, and administrative tasks.

Construction of AppAgent Addresses:

• Build the public key of the address

  • AppAgent ID: app_agent_id

    • The first 4 bytes (bytes 0 to 3) represent the unique identifier of the AppAgent (app_agent_id). This identifier uniquely represents the AppAgent within the system.

  • Address Type Identifier: 1

    • The next byte (4) of the address serves as an identifier to distinguish AppAgent addresses from other types of addresses. In this implementation, the identifier for AppAgent addresses is set to 1.

  • Checksum:

    • The remaining bytes (bytes 5 to 31) are reserved for the checksum to ensure the integrity of the address.

      • The checksum is computed based on:

        1. The concatenation of the AppAgent ID

        2. The address type identifier using the Blake2-256 hashing algorithm

• Convert public key to the address using SS58 encoding

Transactional Addresses:

• Identifier: 2

• Format:

  • Bytes [0:3] - AppAgent ID

  • Byte 4 - Address Identifier

  • Bytes [5:8] - Transactional Address ID

  • Bytes [9:31] - Checksum

• Purpose: Used to manage transactions and deposits.

• Number of available addresses per AppAgent: 4,294,967,295.

• Example Use Case: Receiving deposits from uses, handling funds associated with specific transactions.

Construction of Transactional Addresses:

• Build the public key of the address

  • AppAgent ID: app_agent_id

    • The first 4 bytes (bytes 0 to 3) represent the unique identifier of the associated AppAgent (app_agent_id). This identifier represents the AppAgent responsible for managing the transactional address.

  • Address Type Identifier: 2

    • The next byte (4) of the address serves as an identifier distinguishing Transactional Addresses from other address types. In this implementation, the identifier for Transactional Addresses is set to 2.

  • Transactional Address ID: ta_id

    • Following the type identifier, the next 4 bytes (bytes 5 to 8) represent the unique identifier of the Transactional Address itself (ta_id). This identifier distinguishes individual Transactional Addresses managed by the same AppAgent.

  • Checksum:

    • The remaining bytes (bytes 9 to 31) are reserved for the checksum to ensure the integrity of the address.

    • Similar to AppAgent addresses, the checksum is computed based on the concatenated bytes (AppAgent ID, Address Type Identifier, and Transactional Address ID) using the Blake2-256 hashing algorithm.

• Convert public key to the address using SS58 encoding

Named Addresses:

• Identifier: 3

• Format:

  • Bytes [0:3] - AppAgent ID

  • Byte 4 - Address Identifier

  • Bytes [5:14] - Address Name

  • Bytes [15:31] - Checksum

• Purpose: Provides human-readable labels for addresses, enhancing usability and manageability.

• Example Use Case: Labeling accounts, or specific addresses for easier identification.

Construction of Named Addresses:

• Build the public key of the address

  • AppAgent ID: app_agent_id

    • The first 4 bytes (bytes 0 to 3) represent the unique identifier of the associated app agent (app_agent_id). This identifier identifies the app agent responsible for managing the named address.

  • Address Type Identifier: 3

    • The next byte (4) of the address serves as an identifier, distinguishing Named Addresses from other types. In this implementation, the identifier for named addresses is set to 3.

  • Address Name: name

    • Following the type identifier, the next 10 bytes (bytes 5 to 14) represent the name or label associated with the Named Address (name). This name provides a human-readable identifier for the address.

  • Checksum:

    • The remaining bytes (bytes 15 to 31) are reserved for the checksum to ensure the integrity of the address.

    • As with other address types, the checksum is computed based on the concatenated bytes (AppAgent ID, Address Type Identifier, and Address Name) using the Blake2-256 hashing algorithm.

• Convert public key to the address using SS58 encoding