From cc086f3a126510614f372c57fa1d1a9c38142bd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mathias=20Bj=C3=B6rkqvist?= Date: Tue, 7 Jan 2025 15:20:53 +0100 Subject: [PATCH] docs(ICRC_Ledger): FI-1619: Add rustdoc to icrc-ledger-types (#3345) Add rustdoc to the `icrc-ledger-types`. --- .../src/icrc/generic_metadata_value.rs | 8 +++++++- .../src/icrc/generic_value.rs | 2 ++ packages/icrc-ledger-types/src/icrc/mod.rs | 2 ++ .../icrc-ledger-types/src/icrc1/account.rs | 5 ++++- packages/icrc-ledger-types/src/icrc1/mod.rs | 3 +++ .../icrc-ledger-types/src/icrc1/transfer.rs | 7 +++++++ .../icrc-ledger-types/src/icrc2/allowance.rs | 6 ++++++ .../icrc-ledger-types/src/icrc2/approve.rs | 6 ++++++ packages/icrc-ledger-types/src/icrc2/mod.rs | 2 ++ .../src/icrc2/transfer_from.rs | 6 ++++++ packages/icrc-ledger-types/src/icrc21/mod.rs | 3 +++ .../icrc-ledger-types/src/icrc3/archive.rs | 18 ++++++++++++++++++ packages/icrc-ledger-types/src/icrc3/blocks.rs | 17 ++++++++++++++++- packages/icrc-ledger-types/src/icrc3/mod.rs | 3 +++ packages/icrc-ledger-types/src/icrc3/schema.rs | 1 + .../src/icrc3/transactions.rs | 4 ++++ packages/icrc-ledger-types/src/lib.rs | 2 ++ 17 files changed, 92 insertions(+), 3 deletions(-) diff --git a/packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs b/packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs index a46c9c33bc8..bb5f4d169cd 100644 --- a/packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs +++ b/packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs @@ -2,7 +2,12 @@ use candid::{CandidType, Deserialize, Int, Nat}; use serde::Serialize; use serde_bytes::ByteBuf; -/// Variant type for the `metadata` endpoint values. +/// Variant type for the `icrc1_metadata` endpoint values. The corresponding metadata keys are +/// arbitrary Unicode strings and must follow the pattern `:`, where `` +/// is a string not containing colons. The namespace `icrc1` is reserved for keys defined in the +/// ICRC-1 standard. For more information, see the +/// [documentation of Metadata in the ICRC-1 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1#metadata). +/// Note that the `MetadataValue` type is a subset of the [`icrc_ledger_types::icrc::generic_value::ICRC3Value`] type. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub enum MetadataValue { Nat(Nat), @@ -12,6 +17,7 @@ pub enum MetadataValue { } impl MetadataValue { + /// Create a `(String, MetadataValue)` tuple for use in metadata maps. pub fn entry(key: impl ToString, val: impl Into) -> (String, Self) { (key.to_string(), val.into()) } diff --git a/packages/icrc-ledger-types/src/icrc/generic_value.rs b/packages/icrc-ledger-types/src/icrc/generic_value.rs index c7994cd193f..47b931e0037 100644 --- a/packages/icrc-ledger-types/src/icrc/generic_value.rs +++ b/packages/icrc-ledger-types/src/icrc/generic_value.rs @@ -15,6 +15,7 @@ pub type Map = BTreeMap; pub type ICRC3Map = BTreeMap; pub type Hash = [u8; 32]; +/// A value defined in [the ICRC-3 standard](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value). #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)] pub enum ICRC3Value { Blob(ByteBuf), @@ -33,6 +34,7 @@ impl std::fmt::Display for ICRC3Value { } impl ICRC3Value { + /// Compute [the hash of an ICRC-3 value](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value). pub fn hash(self) -> Hash { // TODO(FI-1263): copy the value hash function to avoid cloning self Value::from(self).hash() diff --git a/packages/icrc-ledger-types/src/icrc/mod.rs b/packages/icrc-ledger-types/src/icrc/mod.rs index 299fac452e6..3ed31f22887 100644 --- a/packages/icrc-ledger-types/src/icrc/mod.rs +++ b/packages/icrc-ledger-types/src/icrc/mod.rs @@ -1,3 +1,5 @@ +//! Types for ICRC standards. + pub mod generic_metadata_value; pub mod generic_value; pub mod generic_value_predicate; diff --git a/packages/icrc-ledger-types/src/icrc1/account.rs b/packages/icrc-ledger-types/src/icrc1/account.rs index 96254ffbd17..3d9e06e836f 100644 --- a/packages/icrc-ledger-types/src/icrc1/account.rs +++ b/packages/icrc-ledger-types/src/icrc1/account.rs @@ -15,7 +15,8 @@ pub type Subaccount = [u8; 32]; pub const DEFAULT_SUBACCOUNT: &Subaccount = &[0; 32]; -// Account representation of ledgers supporting the ICRC1 standard +/// [Account](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value) +/// representation of ledgers supporting the ICRC-1 standard. #[derive(Serialize, CandidType, Deserialize, Clone, Debug, Copy, Encode, Decode)] pub struct Account { #[cbor(n(0), with = "icrc_cbor::principal")] @@ -25,6 +26,8 @@ pub struct Account { } impl Account { + /// The effective subaccount of an account - the subaccount if it is set, otherwise the default + /// subaccount of all zeroes. #[inline] pub fn effective_subaccount(&self) -> &Subaccount { self.subaccount.as_ref().unwrap_or(DEFAULT_SUBACCOUNT) diff --git a/packages/icrc-ledger-types/src/icrc1/mod.rs b/packages/icrc-ledger-types/src/icrc1/mod.rs index 365317be2b5..9e2517c5dd8 100644 --- a/packages/icrc-ledger-types/src/icrc1/mod.rs +++ b/packages/icrc-ledger-types/src/icrc1/mod.rs @@ -1,2 +1,5 @@ +//! The [ICRC-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md) +//! token standard. + pub mod account; pub mod transfer; diff --git a/packages/icrc-ledger-types/src/icrc1/transfer.rs b/packages/icrc-ledger-types/src/icrc1/transfer.rs index ba1e3b62a2e..961d98f8199 100644 --- a/packages/icrc-ledger-types/src/icrc1/transfer.rs +++ b/packages/icrc-ledger-types/src/icrc1/transfer.rs @@ -7,6 +7,7 @@ use std::fmt; pub type NumTokens = Nat; pub type BlockIndex = Nat; +/// The arguments for the [ICRC-1 `transfer`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-) endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct TransferArg { #[serde(default)] @@ -21,6 +22,9 @@ pub struct TransferArg { pub amount: NumTokens, } +/// The [`Memo`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-) +/// is an arbitrary blob that has no meaning to the ledger. The ledger SHOULD allow memos of at +/// least 32 bytes in length. #[derive( Serialize, Deserialize, CandidType, Clone, Hash, Debug, PartialEq, Eq, PartialOrd, Ord, Default, )] @@ -51,6 +55,9 @@ impl From for ByteBuf { } } +/// Errors defined for the +/// [ICRC-1 `transfer`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub enum TransferError { BadFee { expected_fee: NumTokens }, diff --git a/packages/icrc-ledger-types/src/icrc2/allowance.rs b/packages/icrc-ledger-types/src/icrc2/allowance.rs index aebda165fbb..72f9f6a36d8 100644 --- a/packages/icrc-ledger-types/src/icrc2/allowance.rs +++ b/packages/icrc-ledger-types/src/icrc2/allowance.rs @@ -3,12 +3,18 @@ use serde::Serialize; use super::super::icrc1::account::Account; +/// The arguments for the +/// [ICRC-2 `allowance`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct AllowanceArgs { pub account: Account, pub spender: Account, } +/// The `Allowance` response type for the +/// [ICRC-2 `allowance`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct Allowance { pub allowance: Nat, diff --git a/packages/icrc-ledger-types/src/icrc2/approve.rs b/packages/icrc-ledger-types/src/icrc2/approve.rs index b85f625fbdf..b1d68f9bd56 100644 --- a/packages/icrc-ledger-types/src/icrc2/approve.rs +++ b/packages/icrc-ledger-types/src/icrc2/approve.rs @@ -5,6 +5,9 @@ use std::fmt; use super::super::icrc1::account::{Account, Subaccount}; use super::super::icrc1::transfer::Memo; +/// The arguments for the +/// [ICRC-2 `approve`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct ApproveArgs { #[serde(default)] @@ -23,6 +26,9 @@ pub struct ApproveArgs { pub created_at_time: Option, } +/// The error return type for the +/// [ICRC-2 `approve`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub enum ApproveError { BadFee { expected_fee: Nat }, diff --git a/packages/icrc-ledger-types/src/icrc2/mod.rs b/packages/icrc-ledger-types/src/icrc2/mod.rs index 29e6531d0d6..6d59e037dbd 100644 --- a/packages/icrc-ledger-types/src/icrc2/mod.rs +++ b/packages/icrc-ledger-types/src/icrc2/mod.rs @@ -1,3 +1,5 @@ +//! The [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) +//! Approve and Transfer From standard. pub mod allowance; pub mod approve; pub mod transfer_from; diff --git a/packages/icrc-ledger-types/src/icrc2/transfer_from.rs b/packages/icrc-ledger-types/src/icrc2/transfer_from.rs index 33d599fbbd0..f4136e1d216 100644 --- a/packages/icrc-ledger-types/src/icrc2/transfer_from.rs +++ b/packages/icrc-ledger-types/src/icrc2/transfer_from.rs @@ -5,6 +5,9 @@ use std::fmt; use super::super::icrc1::account::{Account, Subaccount}; use super::super::icrc1::transfer::Memo; +/// The arguments for the +/// [ICRC-2 `transfer_from`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct TransferFromArgs { #[serde(default)] @@ -20,6 +23,9 @@ pub struct TransferFromArgs { pub created_at_time: Option, } +/// The error return type for the +/// [ICRC-2 `transfer_from`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub enum TransferFromError { BadFee { expected_fee: Nat }, diff --git a/packages/icrc-ledger-types/src/icrc21/mod.rs b/packages/icrc-ledger-types/src/icrc21/mod.rs index 7017638351d..3b4af7afacc 100644 --- a/packages/icrc-ledger-types/src/icrc21/mod.rs +++ b/packages/icrc-ledger-types/src/icrc21/mod.rs @@ -1,3 +1,6 @@ +//! The [ICRC-21](https://github.com/dfinity/wg-identity-authentication/blob/main/topics/ICRC-21/icrc_21_consent_msg.md) +//! Canister Call Consent Messages standard. + pub mod errors; pub mod lib; pub mod requests; diff --git a/packages/icrc-ledger-types/src/icrc3/archive.rs b/packages/icrc-ledger-types/src/icrc3/archive.rs index ddc69ba4d57..91ad27c9799 100644 --- a/packages/icrc-ledger-types/src/icrc3/archive.rs +++ b/packages/icrc-ledger-types/src/icrc3/archive.rs @@ -8,6 +8,10 @@ use candid::{CandidType, Deserialize, Nat, Principal}; use serde::Serialize; use std::marker::PhantomData; +/// Deprecated. The information in the `ArchivedRange` struct is returned as part of the return value +/// of [`crate::icrc3::blocks::GetBlocksResult`] from the +/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct ArchivedRange { pub start: Nat, @@ -15,6 +19,10 @@ pub struct ArchivedRange { pub callback: Callback, } +/// Details on the callback function using which archived blocks can be retrieved. Returned as part +/// of [`crate::icrc3::blocks::GetBlocksResult`] from the +/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint. #[derive(Debug, Serialize, Deserialize, PartialEq, Eq)] #[serde(try_from = "candid::types::reference::Func")] pub struct QueryArchiveFn { @@ -108,6 +116,7 @@ impl CandidType for QueryArchiveFn; pub type QueryTxArchiveFn = QueryArchiveFn; +/// The argument for the +/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct GetArchivesArgs { // The last archive seen by the client. @@ -126,6 +138,9 @@ pub struct GetArchivesArgs { pub from: Option, } +/// The information returned as part of the return value for the +/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct ICRC3ArchiveInfo { // The id of the archive @@ -138,4 +153,7 @@ pub struct ICRC3ArchiveInfo { pub end: Nat, } +/// The return value for the +/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint. pub type GetArchivesResult = Vec; diff --git a/packages/icrc-ledger-types/src/icrc3/blocks.rs b/packages/icrc-ledger-types/src/icrc3/blocks.rs index 3d44dc263bf..fb4873e54d3 100644 --- a/packages/icrc-ledger-types/src/icrc3/blocks.rs +++ b/packages/icrc-ledger-types/src/icrc3/blocks.rs @@ -8,7 +8,7 @@ use serde_bytes::ByteBuf; use super::archive::QueryArchiveFn; -/// Deprecated, use `ICRC3GenericBlock` instead +/// Deprecated, use [`ICRC3GenericBlock`] instead pub type GenericBlock = Value; pub type ICRC3GenericBlock = ICRC3Value; @@ -22,18 +22,23 @@ pub struct GetBlocksResponse { pub archived_blocks: Vec>, } +/// A block with an ID. Returned as part of [`GetBlocksResult`]. #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct BlockWithId { pub id: Nat, pub block: ICRC3GenericBlock, } +/// Information about where to find archived blocks. Returned as part of [`GetBlocksResult`]. #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct ArchivedBlocks { pub args: Vec, pub callback: QueryArchiveFn, GetBlocksResult>, } +/// The result type for the +/// [ICRC-3 `icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_blocks) +/// endpoint. #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct GetBlocksResult { pub log_length: Nat, @@ -41,12 +46,16 @@ pub struct GetBlocksResult { pub archived_blocks: Vec, } +/// The arguments for the +/// [ICRC-3 `icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_blocks) +/// endpoint. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)] pub struct GetBlocksRequest { pub start: BlockIndex, pub length: Nat, } +/// The return type for the deprecated `get_blocks` endpoint of the archive canister. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct BlockRange { pub blocks: Vec, @@ -81,12 +90,18 @@ pub struct DataCertificate { pub hash_tree: serde_bytes::ByteBuf, } +/// The data certificate returned from the +/// [ICRC-3 `icrc3_get_tip_certificate`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_tip_certificate) +/// endpoint. #[derive(Debug, CandidType, Serialize, Deserialize)] pub struct ICRC3DataCertificate { pub certificate: serde_bytes::ByteBuf, pub hash_tree: serde_bytes::ByteBuf, } +/// The return type of the +/// [ICRC-3 `icrc3_supported_block_types`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_supported_block_types) +/// endpoint. #[derive(Debug, CandidType, Serialize, Deserialize)] pub struct SupportedBlockType { pub block_type: String, diff --git a/packages/icrc-ledger-types/src/icrc3/mod.rs b/packages/icrc-ledger-types/src/icrc3/mod.rs index db50aef6ccf..fd1572dd8ed 100644 --- a/packages/icrc-ledger-types/src/icrc3/mod.rs +++ b/packages/icrc-ledger-types/src/icrc3/mod.rs @@ -1,3 +1,6 @@ +//! The [ICRC-3](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +//! Block Log standard. + pub mod archive; pub mod blocks; pub mod schema; diff --git a/packages/icrc-ledger-types/src/icrc3/schema.rs b/packages/icrc-ledger-types/src/icrc3/schema.rs index 95b1fa75b03..3ebd7453728 100644 --- a/packages/icrc-ledger-types/src/icrc3/schema.rs +++ b/packages/icrc-ledger-types/src/icrc3/schema.rs @@ -8,6 +8,7 @@ use crate::icrc::{ }, }; +/// Validate if a block is compatible with the ICRC-3 schema. // TODO(FI-1241): make it compatible with the final ICRC-3 schema pub fn validate(block: &Value) -> Result<(), ValuePredicateFailures> { use ItemRequirement::*; diff --git a/packages/icrc-ledger-types/src/icrc3/transactions.rs b/packages/icrc-ledger-types/src/icrc3/transactions.rs index ff6fd3575d7..e6f9f06141b 100644 --- a/packages/icrc-ledger-types/src/icrc3/transactions.rs +++ b/packages/icrc-ledger-types/src/icrc3/transactions.rs @@ -113,6 +113,9 @@ impl Transaction { } } +/// Deprecated. Use [`GetBlocksResponse`] returned from the +/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md) +/// endpoint instead. #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct GetTransactionsResponse { pub log_length: Nat, @@ -121,6 +124,7 @@ pub struct GetTransactionsResponse { pub archived_transactions: Vec>, } +/// Deprecated. Use Vec<[`ICRC3GenericBlock`]> instead #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)] pub struct TransactionRange { pub transactions: Vec, diff --git a/packages/icrc-ledger-types/src/lib.rs b/packages/icrc-ledger-types/src/lib.rs index f532acb4880..454b5d6b2cb 100644 --- a/packages/icrc-ledger-types/src/lib.rs +++ b/packages/icrc-ledger-types/src/lib.rs @@ -1,3 +1,5 @@ +//! A library of types to communicate with a ledger canister that implements ICRC standards. + pub mod icrc; pub mod icrc1; pub mod icrc2;