trait_keyless/lib.rs
1//! This module provides functionality for encoding and decoding keyless addresses.
2//!
3//! A keyless address is a type of address that doesn't rely on cryptographic key pairs for identification.
4//! Instead, it is derived from a combination of identifiers and checksums, making it suitable and
5//! convenient for off-chain applications to use.
6//!
7//! # Examples
8//!
9//! ```rust
10//! use trait_keyless::*;
11//!
12//! // Encode an AppAgent keyless address
13//! let app_agent_id = 123;
14//! let app_agent_address = encode_app_agent_account(&app_agent_id);
15//!
16//! // Decode the keyless address
17//! let decoded_app_agent_id = decode_app_agent_account(&app_agent_address).unwrap();
18//! assert_eq!(decoded_app_agent_id, app_agent_id);
19//! ```
20//!
21//! # Keyless Address Structure
22//!
23//! A keyless address consists of two parts:
24//!
25//! - Open Part: Contains specific identifiers or data relevant to the address type.
26//!
27//! - Checksum: A hash-based checksum to ensure address integrity.
28//!
29//! Each keyless address belongs to one of the address types. It can be one of the following:
30//!
31//! - `APP_AGENT_ADDRESS_IDENTIFIER`: Identifies an AppAgent keyless address.
32//! - `TRANSACTIONAL_ADDRESS_IDENTIFIER`: Identifies a Transactional keyless address.
33//! - `NAMED_ADDRESS_IDENTIFIER`: Identifies a Named keyless address.
34//!
35//! Each address type has a different structure for the open part, as described below:
36//!
37//! - **AppAgent Address**:
38//! - [0..=3] -> AppAgentId
39//! - [4..4] -> Address type identifier `APP_AGENT_ADDRESS_IDENTIFIER`
40//! - [5..=31] -> Checksum
41//!
42//! - **Transactional Address**:
43//! - [0..=3] -> AppAgentId
44//! - [4..4] -> Address type identifier `TRANSACTIONAL_ADDRESS_IDENTIFIER`
45//! - [5..=8] -> TransactionalId
46//! - [9..=31] -> Checksum
47//!
48//! - **Named Address**:
49//! - [0..=3] -> AppAgentId
50//! - [4..4] -> Address type identifier `NAMED_ADDRESS_IDENTIFIER`
51//! - [5..=14] -> Address name
52//! - [15..=31] -> Checksum
53//!
54//! # Public Interface
55//!
56//! This module exposes functions to encode, decode, and manipulate keyless addresses:
57//!
58//! - `encode_app_agent_account`: Builds a keyless address for the specified `AppAgentId`.
59//! - `decode_app_agent_account`: Decodes the provided keyless address and retrieves the corresponding `AppAgentId`.
60//! - `encode_transactional_account`: Builds a keyless address for the specified `AppAgentId` and `TransactionalId`.
61//! - `decode_transactional_account`: Decodes the provided keyless address and retrieves the `AppAgentId` and `TransactionalId`.
62//! - `encode_named_account`: Builds a keyless address for the specified `AppAgentId` and `Name`.
63//! - `decode_named_account`: Decodes the provided keyless address and retrieves the `AppAgentId` and `AddressName`.
64//! - `decode_account`: Decodes any type of account, including regular accounts, and provides full information about the account.
65//!
66//! # Errors
67//!
68//! Errors can occur during the encoding or decoding process, such as invalid input or checksum failure.
69//! In such cases, functions return a `Result` containing an error message.
70//!
71//! # Safety
72//!
73//! This module assumes that the provided data types are used correctly and safely.
74//! It's essential to ensure that the input values are valid and within the expected ranges.
75//!
76#![cfg_attr(not(feature = "std"), no_std)]
77mod keyless;
78mod types;
79
80mod tests_binary;
81mod tests_encoding;
82
83pub use keyless::*;
84pub use types::*;