From 470b63481cf52f79ca2a273da1064a883527aece Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Wed, 30 Oct 2024 12:57:56 +0100 Subject: [PATCH 01/22] get git number for the discover index standard --- ICRCs/gitno | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 ICRCs/gitno diff --git a/ICRCs/gitno b/ICRCs/gitno new file mode 100644 index 00000000..e69de29b From 96f9448c6c47cf2dc0e775a5d11de4d0d7bbbe39 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Wed, 30 Oct 2024 13:00:56 +0100 Subject: [PATCH 02/22] initial file --- ICRCs/{gitno => ICRC-106/ICRC-106.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ICRCs/{gitno => ICRC-106/ICRC-106.md} (100%) diff --git a/ICRCs/gitno b/ICRCs/ICRC-106/ICRC-106.md similarity index 100% rename from ICRCs/gitno rename to ICRCs/ICRC-106/ICRC-106.md From ea02f8e7b21e21282d69b8b3ab51bfe87fb9dc88 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Fri, 1 Nov 2024 13:52:11 +0100 Subject: [PATCH 03/22] intro & metadata --- ICRCs/ICRC-106/ICRC-106.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index e69de29b..cf5453fd 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -0,0 +1,30 @@ +| Status | +|:------:| +|Draft| + +# ICRC-106: Standard for Associating Index Canisters with ICRC-1 Tokens + +## 1. Introduction + +Wallet applications and token management tools often need to retrieve both token metadata and transaction history for a given principal. However, identifying an associated index canister for ICRC-1 tokens is currently unstandardized, leading to inconsistencies in wallet integrations. + +**ICRC-106** introduces a standard approach for: +1. Indicating the presence of an index canister for ICRC-1 tokens through ledger metadata. +2. Defining a minimal interface for the index canister to facilitate querying transaction history in a consistent manner. + +This standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. + +--- + +## 2. Metadata + +To indicate the presence of an index canister, ledgers implementing ICRC-106 MUST include the following metadata entry: + +- **`icrc106:index_principal`**: Text entry representing the principal of the index canister associated with the ledger. This metadata entry enables programmatic discovery of the index canister’s principal by wallet applications and other clients. + +### Optional Method + +In addition, ledgers MAY provide an endpoint to retrieve the principal of the index canister: + +```candid +icrc106_get_index_principal : () -> (opt principal) query From 40a3ce74c330cc70627565edf93171644d34ac2b Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 12 Nov 2024 11:41:05 +0100 Subject: [PATCH 04/22] include part of index.did --- ICRCs/ICRC-106/ICRC-106.md | 75 +++++++++++++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 6 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index cf5453fd..2fa859ed 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -14,17 +14,80 @@ Wallet applications and token management tools often need to retrieve both token This standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. ---- ## 2. Metadata -To indicate the presence of an index canister, ledgers implementing ICRC-106 MUST include the following metadata entry: +A ledger implementing ICRC-106 MUST include the following entry in the output of the `icrc1_supported_standards` method: -- **`icrc106:index_principal`**: Text entry representing the principal of the index canister associated with the ledger. This metadata entry enables programmatic discovery of the index canister’s principal by wallet applications and other clients. +```candid +record { name = "ICRC-106"; url = "https://github.com/dfinity/ICRC-1/standards/ICRC-106" } +``` + +Additionally, the ledger MUST provide the following metadata entries accessible via the `icrc1_metadata` method: + +- `icrc106:index_principal` (text): The textual representation of the principal of the associated index canister. +- `icrc106:index_canister_interface` (text): A URL pointing to the Candid interface definition of the index canister. -### Optional Method +These metadata entries allow clients to discover and interact with the index canister associated with a ledger. -In addition, ledgers MAY provide an endpoint to retrieve the principal of the index canister: +Compliant ledgers MAY also implement the following optional endpoint for programmatically retrieving the index principal: ```candid -icrc106_get_index_principal : () -> (opt principal) query +icrc106_get_index_principal: () -> (principal) query; +``` + +## 3. Index Canister Interface + +The index canister associated with the ledger is expected to implement the following minimal Candid interface: + +```candid +type Tokens = nat; + +type Account = record { + owner: principal; + subaccount: opt blob; +}; + +type GetAccountTransactionsArgs = record { + account: Account; + start: opt nat; // The block index of the last transaction seen by the client. + max_results: nat; // Maximum number of transactions to fetch. +}; + +type Transaction = record { + burn: opt record { from: Account; amount: nat; }; + transfer: opt record { from: Account; to: Account; amount: nat; }; + approve: opt record { from: Account; spender: Account; amount: nat; }; + timestamp: nat64; // Timestamp of the transaction. +}; + +type TransactionWithId = record { + id: nat; // Block index of the transaction. + transaction: Transaction; +}; + +type GetTransactionsResult = variant { + Ok: record { + balance: Tokens; // Current balance of the account. + transactions: vec TransactionWithId; // List of transactions. + }; + Err: record { message: text; }; +}; + +service : { + get_account_transactions: (GetAccountTransactionsArgs) -> (GetTransactionsResult) query; + icrc1_balance_of: (Account) -> (Tokens) query; + ledger_id: () -> (principal) query; +} +``` + +This interface defines the minimal set of methods that index canisters must support for integration. + +## 4. Implementation Considerations + +Implementers should ensure that: +- The `icrc106:index_principal` metadata entry accurately reflects the principal of the associated index canister. +- The `icrc106:index_canister_interface` metadata entry points to a location where the Candid interface definition of the index canister is accessible. +- Any changes to the index canister interface should maintain backward compatibility. + +By adhering to ICRC-106, ledger canisters provide a standardized mechanism for clients to discover and interact with their associated index canisters, improving integration and user experience within the Internet Computer ecosystem. From 4c6546408b2e1d51968ad4cc079d752879b86a43 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 12 Nov 2024 13:09:56 +0100 Subject: [PATCH 05/22] specify that metadata can be fetched via icrc1_get_metadata --- ICRCs/ICRC-106/ICRC-106.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 2fa859ed..b26d6229 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -28,7 +28,8 @@ Additionally, the ledger MUST provide the following metadata entries accessible - `icrc106:index_principal` (text): The textual representation of the principal of the associated index canister. - `icrc106:index_canister_interface` (text): A URL pointing to the Candid interface definition of the index canister. -These metadata entries allow clients to discover and interact with the index canister associated with a ledger. +These metadata entries allow clients to discover and interact with the index canister associated with a ledger and can be retrieved using method `icrc1_metadata` defined by the ICRC-1 standard. + Compliant ledgers MAY also implement the following optional endpoint for programmatically retrieving the index principal: From 3566eb97ac732a79ef410ab06072977051fe5ddc Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 12 Nov 2024 16:42:08 +0100 Subject: [PATCH 06/22] added some other methods for the index --- ICRCs/ICRC-106/ICRC-106.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index b26d6229..2758ea94 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -23,10 +23,9 @@ A ledger implementing ICRC-106 MUST include the following entry in the output of record { name = "ICRC-106"; url = "https://github.com/dfinity/ICRC-1/standards/ICRC-106" } ``` -Additionally, the ledger MUST provide the following metadata entries accessible via the `icrc1_metadata` method: +Additionally, the ledger MUST provide the following metadata entry retrievable via the `icrc1_metadata` method: - `icrc106:index_principal` (text): The textual representation of the principal of the associated index canister. -- `icrc106:index_canister_interface` (text): A URL pointing to the Candid interface definition of the index canister. These metadata entries allow clients to discover and interact with the index canister associated with a ledger and can be retrieved using method `icrc1_metadata` defined by the ICRC-1 standard. @@ -44,6 +43,10 @@ The index canister associated with the ledger is expected to implement the follo ```candid type Tokens = nat; +type BlockIndex = nat; + +type SubAccount = blob; + type Account = record { owner: principal; subaccount: opt blob; @@ -75,10 +78,21 @@ type GetTransactionsResult = variant { Err: record { message: text; }; }; +type ListSubaccountsArgs = record { + owner: principal; + start: opt SubAccount; +}; + +type Status = record { + num_blocks_synced : BlockIndex; +}; + service : { get_account_transactions: (GetAccountTransactionsArgs) -> (GetTransactionsResult) query; icrc1_balance_of: (Account) -> (Tokens) query; ledger_id: () -> (principal) query; + list_subaccounts : (ListSubaccountsArgs) -> (vec SubAccount) query; + status : () -> (Status) query; } ``` From 317af75502c25d6c4522e20552e3b8250da11907 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Thu, 14 Nov 2024 15:23:16 +0100 Subject: [PATCH 07/22] method descriptions for the index API? --- ICRCs/ICRC-106/ICRC-106.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 2758ea94..9857d977 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -12,7 +12,7 @@ Wallet applications and token management tools often need to retrieve both token 1. Indicating the presence of an index canister for ICRC-1 tokens through ledger metadata. 2. Defining a minimal interface for the index canister to facilitate querying transaction history in a consistent manner. -This standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. +This draft standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. It will act as a placeholder and documentation source until a more comprehensive standard for index canisters will be developed. ## 2. Metadata @@ -30,7 +30,7 @@ Additionally, the ledger MUST provide the following metadata entry retrievable v These metadata entries allow clients to discover and interact with the index canister associated with a ledger and can be retrieved using method `icrc1_metadata` defined by the ICRC-1 standard. -Compliant ledgers MAY also implement the following optional endpoint for programmatically retrieving the index principal: +Compliant ledgers MUST also implement the following endpoint for programmatically retrieving the index principal: ```candid icrc106_get_index_principal: () -> (principal) query; @@ -96,7 +96,7 @@ service : { } ``` -This interface defines the minimal set of methods that index canisters must support for integration. +This interface defines the minimal set of methods that index canisters must support for integration. The behavior of the methods that are offered is as follows. ## 4. Implementation Considerations From 6ea31c35feb99163b225682eca8a39926f4adf84 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Thu, 14 Nov 2024 16:15:36 +0100 Subject: [PATCH 08/22] remove numbering for API methods --- ICRCs/ICRC-106/ICRC-106.md | 54 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 9857d977..3abcbe8d 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -96,13 +96,63 @@ service : { } ``` -This interface defines the minimal set of methods that index canisters must support for integration. The behavior of the methods that are offered is as follows. + +# Methods Provided by the Index Canister + +The index canister provides methods to facilitate querying of transaction history and metadata associated with accounts. Below is a description of the relevant methods specified in this standard, including their purpose, input, output, and typical use case. + +--- + +## get_account_transactions +- **Purpose**: Retrieves transactions associated with a specific account, starting from a specified block index and returning up to a maximum number of results. Transactions are returned in **reverse chronological order** (newest to oldest). +- **Input**: + - `account`: The account (principal and optional subaccount) for which transactions are to be fetched. + - `start`: *(Optional)* The block index of the most recent transaction the client has already seen. If provided, only transactions with block indices **less than** this value will be returned. + - `max_results`: The maximum number of transactions to return. +- **Output**: + - **`Ok`**: Returns a record containing: + - `balance`: The current token balance of the account. + - `transactions`: A vector of `TransactionWithId`, each containing: + - `id`: The block index of the transaction. + - `transaction`: Details of the transaction (burn, transfer, approval, and timestamp). + - `oldest_tx_id`: *(Optional)* The block index of the oldest transaction for the account, or `None` if no transactions exist. + - **`Err`**: Returns an error message explaining why the request could not be completed (e.g., invalid input). +- **Typical Use Case**: This method is often used by wallets to display transaction history and update account balances. It also supports paginated transaction retrieval for efficient history browsing. + +--- + +## ledger_id +- **Purpose**: Retrieves the principal of the ledger canister that the index is linked to. +- **Input**: None. +- **Output**: The `principal` of the ledger canister. +- **Typical Use Case**: This method is primarily used for validating the relationship between the index and the ledger, ensuring they are correctly linked, and facilitating integrations requiring the ledger’s identity. + +--- + +## list_subaccounts +- **Purpose**: Lists all subaccounts associated with a specified principal. +- **Input**: + - `owner`: The principal for which to list subaccounts. + - `start`: *(Optional)* Specifies the subaccount to start listing from. Only subaccounts lexicographically greater than `start` will be included. +- **Output**: A vector of `SubAccount`, each representing a subaccount under the specified principal. +- **Typical Use Case**: Useful for wallets or tools that need to enumerate all subaccounts associated with a user, providing insight into the structure and organization of user funds. + +--- + +## status +- **Purpose**: Retrieves the synchronization and operational status of the index canister. +- **Input**: None. +- **Output**: A `Status` record containing: + - `num_blocks_synced`: The total number of blocks that have been successfully synchronized by the index canister. +- **Typical Use Case**: Used for monitoring the health and synchronization status of the index, this method is helpful for determining whether the index has fully caught up with the ledger and is operational. + + + ## 4. Implementation Considerations Implementers should ensure that: - The `icrc106:index_principal` metadata entry accurately reflects the principal of the associated index canister. -- The `icrc106:index_canister_interface` metadata entry points to a location where the Candid interface definition of the index canister is accessible. - Any changes to the index canister interface should maintain backward compatibility. By adhering to ICRC-106, ledger canisters provide a standardized mechanism for clients to discover and interact with their associated index canisters, improving integration and user experience within the Internet Computer ecosystem. From 374be3536c0ae72cee5aa9b5c877e6e31202d32a Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Thu, 14 Nov 2024 17:04:45 +0100 Subject: [PATCH 09/22] fixed the link to the standard --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 3abcbe8d..13458fa7 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -20,7 +20,7 @@ This draft standard aims to improve interoperability, simplify wallet integratio A ledger implementing ICRC-106 MUST include the following entry in the output of the `icrc1_supported_standards` method: ```candid -record { name = "ICRC-106"; url = "https://github.com/dfinity/ICRC-1/standards/ICRC-106" } +record { name = "ICRC-106"; url = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-106" } ``` Additionally, the ledger MUST provide the following metadata entry retrievable via the `icrc1_metadata` method: From 98838cfff3e0f848886a4c9f5b99a739bbc388d0 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Thu, 14 Nov 2024 17:53:37 +0100 Subject: [PATCH 10/22] no error handlingin get_account_transactions description --- ICRCs/ICRC-106/ICRC-106.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 13458fa7..2afb6135 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -12,7 +12,7 @@ Wallet applications and token management tools often need to retrieve both token 1. Indicating the presence of an index canister for ICRC-1 tokens through ledger metadata. 2. Defining a minimal interface for the index canister to facilitate querying transaction history in a consistent manner. -This draft standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. It will act as a placeholder and documentation source until a more comprehensive standard for index canisters will be developed. +This draft standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. It acts as a placeholder and documentation source until a more comprehensive standard for index canisters will be developed. ## 2. Metadata @@ -116,9 +116,19 @@ The index canister provides methods to facilitate querying of transaction histor - `id`: The block index of the transaction. - `transaction`: Details of the transaction (burn, transfer, approval, and timestamp). - `oldest_tx_id`: *(Optional)* The block index of the oldest transaction for the account, or `None` if no transactions exist. - - **`Err`**: Returns an error message explaining why the request could not be completed (e.g., invalid input). - **Typical Use Case**: This method is often used by wallets to display transaction history and update account balances. It also supports paginated transaction retrieval for efficient history browsing. +--- + +## list_subaccounts +- **Purpose**: Lists all subaccounts associated with a specified principal. +- **Input**: + - `owner`: The principal for which to list subaccounts. + - `start`: *(Optional)* Specifies the subaccount to start listing from. Only subaccounts lexicographically greater than `start` will be included. If start is omitted, the method will return all subaccounts from the beginning of the list, ordered lexicographically. +- **Output**: A vector of `SubAccount`, each representing a subaccount under the specified principal. The list will be empty if the principal has not used subaccounts, or if there are no subaccounts lexicographically higher than `start`. +- **Typical Use Case**: Useful for wallets or tools that need to enumerate all subaccounts associated with a user, providing insight into the structure and organization of user funds. + + --- ## ledger_id @@ -127,15 +137,6 @@ The index canister provides methods to facilitate querying of transaction histor - **Output**: The `principal` of the ledger canister. - **Typical Use Case**: This method is primarily used for validating the relationship between the index and the ledger, ensuring they are correctly linked, and facilitating integrations requiring the ledger’s identity. ---- - -## list_subaccounts -- **Purpose**: Lists all subaccounts associated with a specified principal. -- **Input**: - - `owner`: The principal for which to list subaccounts. - - `start`: *(Optional)* Specifies the subaccount to start listing from. Only subaccounts lexicographically greater than `start` will be included. -- **Output**: A vector of `SubAccount`, each representing a subaccount under the specified principal. -- **Typical Use Case**: Useful for wallets or tools that need to enumerate all subaccounts associated with a user, providing insight into the structure and organization of user funds. --- From 13aaa608baf506c71141bbc11232d8fc402ab0c5 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Mon, 18 Nov 2024 15:13:59 +0100 Subject: [PATCH 11/22] refinement of the Transaction types, fixex missing info --- ICRCs/ICRC-106/ICRC-106.md | 67 ++++++++++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 10 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 2afb6135..d89543b4 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -36,9 +36,17 @@ Compliant ledgers MUST also implement the following endpoint for programmaticall icrc106_get_index_principal: () -> (principal) query; ``` +The metadata entry `icrc106:index_principal` and the `icrc106_get_index_principal` method MUST provide consistent information. Specifically: + +- The `icrc106:index_principal` metadata entry MUST represent the textual form of the principal returned by the `icrc106_get_index_principal` method. +- The `icrc106_get_index_principal` method MUST return the principal corresponding to the index canister associated with the ledger, as specified in the `icrc106:index_principal` metadata entry. + +This requirement ensures that both mechanisms reliably point to the same index canister. Implementations + + ## 3. Index Canister Interface -The index canister associated with the ledger is expected to implement the following minimal Candid interface: +The index canister associated with the ledger SHOULD implement the following minimal Candid interface: ```candid type Tokens = nat; @@ -49,31 +57,63 @@ type SubAccount = blob; type Account = record { owner: principal; - subaccount: opt blob; + subaccount: opt SubAccount; }; type GetAccountTransactionsArgs = record { account: Account; - start: opt nat; // The block index of the last transaction seen by the client. + start: opt BlockIndex; // The block index of the last transaction seen by the client. max_results: nat; // Maximum number of transactions to fetch. }; +type Burn = record { + from : Account; + memo : opt vec nat8; + created_at_time : opt nat64; + amount : nat; + spender : opt Account; +}; + +type Transfer = record { + to : Account; + fee : opt nat; + from : Account; + memo : opt vec nat8; + created_at_time : opt nat64; + amount : nat; + spender : opt Account; +}; + +type Approve = record { + fee : opt nat; + from : Account; + memo : opt vec nat8; + created_at_time : opt nat64; + amount : nat; + expected_allowance : opt nat; + expires_at : opt nat64; + spender : Account; +}; + type Transaction = record { - burn: opt record { from: Account; amount: nat; }; - transfer: opt record { from: Account; to: Account; amount: nat; }; - approve: opt record { from: Account; spender: Account; amount: nat; }; - timestamp: nat64; // Timestamp of the transaction. + burn : opt Burn; + kind : text; + mint : opt Mint; + approve : opt Approve; + timestamp : nat64; + transfer : opt Transfer; }; type TransactionWithId = record { - id: nat; // Block index of the transaction. - transaction: Transaction; + id : BlockIndex; + transaction : Transaction; }; type GetTransactionsResult = variant { Ok: record { balance: Tokens; // Current balance of the account. transactions: vec TransactionWithId; // List of transactions. + oldest_tx_id : opt BlockIndex; // The txid of the oldest transaction the account has. }; Err: record { message: text; }; }; @@ -89,7 +129,6 @@ type Status = record { service : { get_account_transactions: (GetAccountTransactionsArgs) -> (GetTransactionsResult) query; - icrc1_balance_of: (Account) -> (Tokens) query; ledger_id: () -> (principal) query; list_subaccounts : (ListSubaccountsArgs) -> (vec SubAccount) query; status : () -> (Status) query; @@ -97,6 +136,7 @@ service : { ``` + # Methods Provided by the Index Canister The index canister provides methods to facilitate querying of transaction history and metadata associated with accounts. Below is a description of the relevant methods specified in this standard, including their purpose, input, output, and typical use case. @@ -148,6 +188,13 @@ The index canister provides methods to facilitate querying of transaction histor - **Typical Use Case**: Used for monitoring the health and synchronization status of the index, this method is helpful for determining whether the index has fully caught up with the ledger and is operational. +## Undocumented Methods +The index canister described in this standard implements several methods beyond those explicitly documented here. While `get_account_transactions`, `list_subaccounts`, `ledger_id`, and `status` are the primary focus of this standard due to their direct relevance to wallet services, the following methods are also part of the index canister interface: + +* `get_blocks`: Allows fetching raw block data for a specified range of indices. +* `get_fee_collectors_ranges`: Provides detailed information about fee collection, including the accounts and block ranges associated with collected fees. +* `icrc1_balance_of`: Enables querying the token balance of specific accounts. + ## 4. Implementation Considerations From 43d368ba79d30e850a422fd693b827b528c26ff1 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Mon, 18 Nov 2024 16:12:06 +0100 Subject: [PATCH 12/22] adjusted the text of the undocumented methods --- ICRCs/ICRC-106/ICRC-106.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index d89543b4..ba66b742 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -188,12 +188,16 @@ The index canister provides methods to facilitate querying of transaction histor - **Typical Use Case**: Used for monitoring the health and synchronization status of the index, this method is helpful for determining whether the index has fully caught up with the ledger and is operational. -## Undocumented Methods -The index canister described in this standard implements several methods beyond those explicitly documented here. While `get_account_transactions`, `list_subaccounts`, `ledger_id`, and `status` are the primary focus of this standard due to their direct relevance to wallet services, the following methods are also part of the index canister interface: +## Optional Methods + +While the methods defined in this standard are sufficient for compliance with ICRC-106, certain implementations of the index canister may include additional methods to extend functionality. These methods are not required by ICRC-106 but may be present for advanced use cases: + +- **`get_blocks`**: Fetches raw block data for a specified range of indices. This is useful for applications requiring detailed historical data. +- **`get_fee_collectors_ranges`**: Provides detailed information about fee collection, including accounts and associated block ranges. +- **`icrc1_balance_of`**: Queries the token balance of specific accounts. This method is commonly used for token management in wallets and tools. + +These methods, while potentially helpful, are outside the scope of ICRC-106 and are not guaranteed to be present in all index canisters. Developers should refer to the documentation of the specific implementation they are working with for details on these optional methods. -* `get_blocks`: Allows fetching raw block data for a specified range of indices. -* `get_fee_collectors_ranges`: Provides detailed information about fee collection, including the accounts and block ranges associated with collected fees. -* `icrc1_balance_of`: Enables querying the token balance of specific accounts. From 9c650524e279982dda6795c8f175aa81d1aa8f15 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 19 Nov 2024 23:43:39 +0100 Subject: [PATCH 13/22] fixes --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index ba66b742..c2e545e1 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -41,7 +41,7 @@ The metadata entry `icrc106:index_principal` and the `icrc106_get_index_principa - The `icrc106:index_principal` metadata entry MUST represent the textual form of the principal returned by the `icrc106_get_index_principal` method. - The `icrc106_get_index_principal` method MUST return the principal corresponding to the index canister associated with the ledger, as specified in the `icrc106:index_principal` metadata entry. -This requirement ensures that both mechanisms reliably point to the same index canister. Implementations +This requirement ensures that both mechanisms reliably point to the same index canister. ## 3. Index Canister Interface From d45963b2cd6543dddea4255f72a31d7781df8768 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Wed, 20 Nov 2024 15:22:08 +0100 Subject: [PATCH 14/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index c2e545e1..c1957fab 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -128,7 +128,7 @@ type Status = record { }; service : { - get_account_transactions: (GetAccountTransactionsArgs) -> (GetTransactionsResult) query; + get_account_transactions: (GetAccountTransactionsArgs) -> (GetAccountTransactionsResult) query; ledger_id: () -> (principal) query; list_subaccounts : (ListSubaccountsArgs) -> (vec SubAccount) query; status : () -> (Status) query; From fca083d12d6eaf6cbfd273e192169a2df2d7f92d Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Wed, 20 Nov 2024 15:22:38 +0100 Subject: [PATCH 15/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index c1957fab..f8b00332 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -196,7 +196,7 @@ While the methods defined in this standard are sufficient for compliance with IC - **`get_fee_collectors_ranges`**: Provides detailed information about fee collection, including accounts and associated block ranges. - **`icrc1_balance_of`**: Queries the token balance of specific accounts. This method is commonly used for token management in wallets and tools. -These methods, while potentially helpful, are outside the scope of ICRC-106 and are not guaranteed to be present in all index canisters. Developers should refer to the documentation of the specific implementation they are working with for details on these optional methods. +These methods, while potentially helpful, are outside the scope of this standard and are thus not guaranteed to be present in all ICRC-106-compliant index canisters. From 64cbbebf15ddf29279697f0b1160be968a3f8538 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Wed, 20 Nov 2024 15:24:01 +0100 Subject: [PATCH 16/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index f8b00332..9b686ad7 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -53,7 +53,7 @@ type Tokens = nat; type BlockIndex = nat; -type SubAccount = blob; +type Subaccount = blob; type Account = record { owner: principal; From 6cce7cdf7b89f6561f97f2d14e9f39909578e8d1 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:36:11 +0100 Subject: [PATCH 17/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 9b686ad7..ba2315d6 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -90,7 +90,7 @@ type Approve = record { memo : opt vec nat8; created_at_time : opt nat64; amount : nat; - expected_allowance : opt nat; + expected_allowance : opt Tokens; expires_at : opt nat64; spender : Account; }; From a98a389ead0527b69d9b71f0bcc21b2bb57e37ad Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:48:17 +0100 Subject: [PATCH 18/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index ba2315d6..188c0f40 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -76,7 +76,7 @@ type Burn = record { type Transfer = record { to : Account; - fee : opt nat; + fee : opt Tokens; from : Account; memo : opt vec nat8; created_at_time : opt nat64; From 9febeb5f859e92140149bc1147851be0ea590515 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:48:32 +0100 Subject: [PATCH 19/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 188c0f40..9def6262 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -80,7 +80,7 @@ type Transfer = record { from : Account; memo : opt vec nat8; created_at_time : opt nat64; - amount : nat; + amount : Tokens; spender : opt Account; }; From c088a31dacbf949412ac98ba7dc9dfc996d293a5 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:48:42 +0100 Subject: [PATCH 20/22] Update ICRCs/ICRC-106/ICRC-106.md Co-authored-by: Arshavir Ter-Gabrielyan --- ICRCs/ICRC-106/ICRC-106.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index 9def6262..e53230ec 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -85,7 +85,7 @@ type Transfer = record { }; type Approve = record { - fee : opt nat; + fee : opt Tokens; from : Account; memo : opt vec nat8; created_at_time : opt nat64; From 95078c40ea71ad89776132e2dc4bedf3ccf43914 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:56:45 +0100 Subject: [PATCH 21/22] beautified .did; explain the use of subaccount listing --- ICRCs/ICRC-106/ICRC-106.md | 46 +++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index e53230ec..e32c90b7 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -41,7 +41,7 @@ The metadata entry `icrc106:index_principal` and the `icrc106_get_index_principa - The `icrc106:index_principal` metadata entry MUST represent the textual form of the principal returned by the `icrc106_get_index_principal` method. - The `icrc106_get_index_principal` method MUST return the principal corresponding to the index canister associated with the ledger, as specified in the `icrc106:index_principal` metadata entry. -This requirement ensures that both mechanisms reliably point to the same index canister. +This requirement ensures that both mechanisms reliably point to the same index canister. ## 3. Index Canister Interface @@ -53,7 +53,7 @@ type Tokens = nat; type BlockIndex = nat; -type Subaccount = blob; +type SubAccount = blob; type Account = record { owner: principal; @@ -68,17 +68,24 @@ type GetAccountTransactionsArgs = record { type Burn = record { from : Account; - memo : opt vec nat8; + memo : opt blob; created_at_time : opt nat64; - amount : nat; + amount : Tokens; spender : opt Account; }; +type Mint = record { + to : Account; + memo : opt blob; + created_at_time : opt nat64; + amount : Tokens; +}; + type Transfer = record { to : Account; fee : opt Tokens; from : Account; - memo : opt vec nat8; + memo : opt blob; created_at_time : opt nat64; amount : Tokens; spender : opt Account; @@ -87,9 +94,9 @@ type Transfer = record { type Approve = record { fee : opt Tokens; from : Account; - memo : opt vec nat8; + memo : opt blob; created_at_time : opt nat64; - amount : nat; + amount : Tokens; expected_allowance : opt Tokens; expires_at : opt nat64; spender : Account; @@ -109,13 +116,20 @@ type TransactionWithId = record { transaction : Transaction; }; -type GetTransactionsResult = variant { - Ok: record { - balance: Tokens; // Current balance of the account. - transactions: vec TransactionWithId; // List of transactions. - oldest_tx_id : opt BlockIndex; // The txid of the oldest transaction the account has. - }; - Err: record { message: text; }; +type GetTransactions = record { + balance : Tokens; + transactions : vec TransactionWithId; + // The txid of the oldest transaction the account has + oldest_tx_id : opt BlockIndex; +}; + +type GetTransactionsErr = record { + message : text; +}; + +type GetAccountTransactionsResult = variant { + Ok : GetTransactions; + Err : GetTransactionsErr; }; type ListSubaccountsArgs = record { @@ -166,7 +180,7 @@ The index canister provides methods to facilitate querying of transaction histor - `owner`: The principal for which to list subaccounts. - `start`: *(Optional)* Specifies the subaccount to start listing from. Only subaccounts lexicographically greater than `start` will be included. If start is omitted, the method will return all subaccounts from the beginning of the list, ordered lexicographically. - **Output**: A vector of `SubAccount`, each representing a subaccount under the specified principal. The list will be empty if the principal has not used subaccounts, or if there are no subaccounts lexicographically higher than `start`. -- **Typical Use Case**: Useful for wallets or tools that need to enumerate all subaccounts associated with a user, providing insight into the structure and organization of user funds. +- **Typical Use Case**: Useful for wallets or tools that need to enumerate *all* subaccounts associated with a user. To get all subaccounts, start with no start parameter and repeatedly call the method, updating start with the last subaccount from each response, until the returned list is empty. --- @@ -196,7 +210,7 @@ While the methods defined in this standard are sufficient for compliance with IC - **`get_fee_collectors_ranges`**: Provides detailed information about fee collection, including accounts and associated block ranges. - **`icrc1_balance_of`**: Queries the token balance of specific accounts. This method is commonly used for token management in wallets and tools. -These methods, while potentially helpful, are outside the scope of this standard and are thus not guaranteed to be present in all ICRC-106-compliant index canisters. +These methods, while potentially helpful, are outside the scope of ICRC-106 and are not guaranteed to be present in all index canisters. Developers should refer to the documentation of the specific implementation they are working with for details on these optional methods. From 2fee16928bad30c7504115bda42b0d0568c3345f Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 26 Nov 2024 12:04:32 +0100 Subject: [PATCH 22/22] clarify the scope of the standard --- ICRCs/ICRC-106/ICRC-106.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ICRCs/ICRC-106/ICRC-106.md b/ICRCs/ICRC-106/ICRC-106.md index e32c90b7..564c832e 100644 --- a/ICRCs/ICRC-106/ICRC-106.md +++ b/ICRCs/ICRC-106/ICRC-106.md @@ -8,9 +8,9 @@ Wallet applications and token management tools often need to retrieve both token metadata and transaction history for a given principal. However, identifying an associated index canister for ICRC-1 tokens is currently unstandardized, leading to inconsistencies in wallet integrations. -**ICRC-106** introduces a standard approach for: -1. Indicating the presence of an index canister for ICRC-1 tokens through ledger metadata. -2. Defining a minimal interface for the index canister to facilitate querying transaction history in a consistent manner. +Standard **ICRC-106** : +1. Introduces a standard approach for indicating the presence of an index canister for ICRC-1 tokens through ledger metadata. +2. Defines a minimal interface for the associated index canister to facilitate querying transaction history in a consistent manner. This draft standard aims to improve interoperability, simplify wallet integrations, and enable token-related applications to reliably access transaction histories. It acts as a placeholder and documentation source until a more comprehensive standard for index canisters will be developed. @@ -97,7 +97,7 @@ type Approve = record { memo : opt blob; created_at_time : opt nat64; amount : Tokens; - expected_allowance : opt Tokens; + expected_allowance : opt nat; expires_at : opt nat64; spender : Account; };