Skip to content

Latest commit

 

History

History
192 lines (148 loc) · 7 KB

icrc_27_get_icrc_1_accounts.md

File metadata and controls

192 lines (148 loc) · 7 KB

ICRC-27: Get ICRC-1 Accounts

Status Badge Extension Badge

Summary

The purpose of the icrc27_get_icrc1_accounts message is for the relying party to receive ICRC-1 accounts managed by the signer.

There are many types of signers:

  • Signers that support many different standards
  • Signers that keep a list of accounts per ledger
  • Signers that keep a list of accounts used across all ledgers

The scope of this spec is limited to ICRC-1 standard ledgers, the accounts returned in this spec contain additional optional information name and canisterIds to indicate with which ledgers the accounts are meant to be used.

Use-Case

The relying party can use this information to manage funds held by these accounts.

Example usages:

  • Relying party needs to know which account to request a transfer of ICP tokens to make a payment.
  • Relying party needs to know all accounts to create tax reports.
  • Relying party needs to know the ckBTC accounts to make a ckBTC payment.
  • Relying party needs to know all accounts to show all tokens the user holds and is able to swap on the dex.

Method

Name: icrc27_get_icrc1_accounts

Prerequisite: Active session with granted permission scope icrc27_get_icrc1_accounts or *.

Scope (according to the ICRC-25 standard)

Scope: icrc27_get_icrc1_accounts

Example Permission Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "icrc25_request_permissions",
  "params": {
    "scopes": [
      {
        "method": "icrc27_get_icrc1_accounts"
      }
    ]
  }
}

icrc25_supported_standards

An ICRC-25 compliant signer must implement the icrc25_supported_standards method which returns the list of supported standards. Any signer implementing ICRC-27 must include a record with the name field equal to "ICRC-27" in that list.

Request Params

None

Example RPC Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "icrc27_get_icrc1_accounts"
}

Result

accounts (vec): List of ICRC-1 accounts.

  • principal (text): Principal (textual representation) used to derive the account identity.
  • subaccount (blob): Subaccount bytes used to derive the account identity, this is 32 bytes as defined in the ICRC-1 ledger standard.
  • canisterIds (opt vec principal): Optional list of ledger canister ids for this account, account is assumed to be for any ICRC-1 ledger canister if undefined.
  • name (opt text): Optional name for this account.

Example RPC Response

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "accounts": [
      {
        "principal": "gyu2j-2ni7o-o6yjt-n7lyh-x3sxq-zh7hp-sjvqe-t7oul-4eehb-2gvtt-jae",
        "subaccount": "0000000000000000000000000000000000000000000000000000000000e73f5c",
        "canisterIds": [
          "ryjl3-tyaaa-aaaaa-aaaba-cai"
        ],
        "name": "Account 3"
      }
    ]
  }
}

Message Processing

  1. The relying party sends a icrc27_get_icrc1_accounts request to the signer.
  2. Upon receiving the message, the signer first checks if it can process the message.
    • If the relying party has not been granted the permission to invoke the method for the specified principal, the signer sends a response with an error back to the relying party.
  3. The signer MUST always prompt the user to select which ICRC-1 accounts to share with the relying party
    • This step MAY only be skipped if the signer does not support user interaction, it MUST not be skipped by e.g. returning previously selected ICRC-1 accounts.
  4. The signer sends a response to the relying party with the list of ICRC-1 accounts selected by the user.
sequenceDiagram
    participant RP as Relying Party
    participant S as Signer
    participant U as User
    RP ->> S: Request ICRC-1 accounts
    alt Scope `icrc27_get_icrc1_accounts` not granted
        S ->> RP: Error response: Permission not granted (3000)
    else
        S ->> U: Prompt to select ICRC-1 accounts
        U ->> S: Select ICRC-1 accounts
        S ->> RP: List of ICRC-1 accounts
    end
Loading

Errors

This standard does not define additional errors. See ICRC-25 for a list of errors that can be returned by all methods.

Ledger index canister accounts

Since the ICRC-1 ledger index canister is able to return all subaccounts for a given principal one could argue that the ICRC-27 standard can be replaced by requesting the principals with the ICRC-31 standard and using the index canister to look up the subaccounts.

But, this is not recommended for relying parties in most use cases for the following reasons:

  • There's no way of knowing about new unused accounts within the ledger
  • The user might not want to use some of these accounts
  • The principals returned by ICRC-31 might not be the same principals that the signer uses for ICRC-1 accounts
  • The signer might not control the ICRC-1 accounts directly but indirectly has access to a limited set of subaccounts in e.g. a canister that holds funds for multiple users sharing the same principal.

The ICRC-27 standard guarantees that the ICRC-1 accounts shared by the signer and received by the relying party, are accessible and under (in)direct control of the signer.

Default subaccount

The default ICRC-1 account must always be explicitly defined in the accounts response when available. The relying party should not assume the default ICRC-1 account based on the principal and zeroed subaccount itself. Some wallets might not return an ICRC-1 account with a zeroed subaccount because they don't use and/or support it.

Other ledger standards

Other ledger standards, for example ICRC-7 can also extend the ICRC-25 standard by creating a new standard based on the ICRC-27 standard.

Signers should not return accounts for other ledger standards besides ICRC-1 in the ICRC-27 standard, doing so would put relying parties at risk of sending tokens to unsupported ledgers.