feat: icrc-2 support in ledger-js

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ## Features
 
+- add support for `icrc2_transfer_from`, `icrc2_approve` and `icrc2_allowance` in `@dfinity/ledger`
 - update index did definitions in ledger which provides more information in the transactions
 
 ## Build

package.json

@@ -85,7 +85,7 @@
     {
       "name": "@dfinity/ledger",
       "path": "./packages/ledger/dist/index.js",
-      "limit": "3 kB",
+      "limit": "4 kB",
       "ignore": [
         "@dfinity/agent",
         "@dfinity/candid",

packages/ledger/README.md

@@ -123,7 +123,7 @@ Parameters:
 
 ### :factory: IcrcLedgerCanister
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L16)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L27)
 
 #### Methods
 
@@ -133,14 +133,17 @@ Parameters:
 - [balance](#gear-balance)
 - [transfer](#gear-transfer)
 - [totalTokensSupply](#gear-totaltokenssupply)
+- [transferFrom](#gear-transferfrom)
+- [approve](#gear-approve)
+- [allowance](#gear-allowance)
 
 ##### :gear: create
 
 | Method   | Type                                                                   |
 | -------- | ---------------------------------------------------------------------- |
 | `create` | `(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L17)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L28)
 
 ##### :gear: metadata
 
@@ -150,7 +153,7 @@ The token metadata (name, symbol, etc.).
 | ---------- | ------------------------------------------------------------- |
 | `metadata` | `(params: QueryParams) => Promise<IcrcTokenMetadataResponse>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L31)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L42)
 
 ##### :gear: transactionFee
 
@@ -160,7 +163,7 @@ The ledger transaction fees.
 | ---------------- | ------------------------------------------ |
 | `transactionFee` | `(params: QueryParams) => Promise<bigint>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L39)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L50)
 
 ##### :gear: balance
 
@@ -174,7 +177,7 @@ Parameters:
 
 - `params`: The parameters to get the balance of an account.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L48)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L59)
 
 ##### :gear: transfer
 
@@ -188,7 +191,7 @@ Parameters:
 
 - `params`: The parameters to transfer tokens.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L61)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L72)
 
 ##### :gear: totalTokensSupply
 
@@ -198,7 +201,55 @@ Returns the total supply of tokens.
 | ------------------- | ------------------------------------------ |
 | `totalTokensSupply` | `(params: QueryParams) => Promise<bigint>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L77)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L88)
+
+##### :gear: transferFrom
+
+Transfers a token amount from the `from` account to the `to` account using the allowance of the spender's account (`SpenderAccount = { owner = caller; subaccount = spender_subaccount }`). The ledger draws the fees from the `from` account.
+
+Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from
+
+| Method         | Type                                              |
+| -------------- | ------------------------------------------------- |
+| `transferFrom` | `(params: TransferFromParams) => Promise<bigint>` |
+
+Parameters:
+
+- `params`: The parameters to transfer tokens from to.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L101)
+
+##### :gear: approve
+
+This method entitles the `spender` to transfer token `amount` on behalf of the caller from account `{ owner = caller; subaccount = from_subaccount }`.
+
+Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve
+
+| Method    | Type                                         |
+| --------- | -------------------------------------------- |
+| `approve` | `(params: ApproveParams) => Promise<bigint>` |
+
+Parameters:
+
+- `params`: The parameters to approve.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L123)
+
+##### :gear: allowance
+
+Returns the token allowance that the `spender` account can transfer from the specified `account`, and the expiration time for that allowance, if any.
+
+Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance
+
+| Method      | Type                                              |
+| ----------- | ------------------------------------------------- |
+| `allowance` | `(params: AllowanceParams) => Promise<Allowance>` |
+
+Parameters:
+
+- `params`: The parameters to call the allowance.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L145)
 
 ### :factory: IcrcIndexCanister
 

packages/ledger/candid/icrc1_ledger.certified.idl.js

@@ -16,30 +16,40 @@ export const idlFactory = ({ IDL }) => {
     'SetTo' : Account,
     'Unset' : IDL.Null,
   });
+  const FeatureFlags = IDL.Record({ 'icrc2' : IDL.Bool });
   const UpgradeArgs = IDL.Record({
     'token_symbol' : IDL.Opt(IDL.Text),
-    'transfer_fee' : IDL.Opt(IDL.Nat64),
+    'transfer_fee' : IDL.Opt(IDL.Nat),
     'metadata' : IDL.Opt(IDL.Vec(IDL.Tuple(IDL.Text, MetadataValue))),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
     'change_fee_collector' : IDL.Opt(ChangeFeeCollector),
     'max_memo_length' : IDL.Opt(IDL.Nat16),
     'token_name' : IDL.Opt(IDL.Text),
+    'feature_flags' : IDL.Opt(FeatureFlags),
   });
   const InitArgs = IDL.Record({
+    'decimals' : IDL.Opt(IDL.Nat8),
     'token_symbol' : IDL.Text,
-    'transfer_fee' : IDL.Nat64,
+    'transfer_fee' : IDL.Nat,
     'metadata' : IDL.Vec(IDL.Tuple(IDL.Text, MetadataValue)),
     'minting_account' : Account,
-    'initial_balances' : IDL.Vec(IDL.Tuple(Account, IDL.Nat64)),
+    'initial_balances' : IDL.Vec(IDL.Tuple(Account, IDL.Nat)),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
     'fee_collector_account' : IDL.Opt(Account),
     'archive_options' : IDL.Record({
       'num_blocks_to_archive' : IDL.Nat64,
+      'max_transactions_per_response' : IDL.Opt(IDL.Nat64),
       'trigger_threshold' : IDL.Nat64,
       'max_message_size_bytes' : IDL.Opt(IDL.Nat64),
       'cycles_for_archive_creation' : IDL.Opt(IDL.Nat64),
       'node_max_memory_size_bytes' : IDL.Opt(IDL.Nat64),
       'controller_id' : IDL.Principal,
     }),
+    'max_memo_length' : IDL.Opt(IDL.Nat16),
     'token_name' : IDL.Text,
+    'feature_flags' : IDL.Opt(FeatureFlags),
   });
   const LedgerArg = IDL.Variant({
     'Upgrade' : IDL.Opt(UpgradeArgs),
@@ -87,35 +97,45 @@ export const idlFactory = ({ IDL }) => {
     'start' : TxIndex,
     'length' : IDL.Nat,
   });
+  const Burn = IDL.Record({
+    'from' : Account,
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(IDL.Nat64),
+    'amount' : IDL.Nat,
+    'spender' : IDL.Opt(Account),
+  });
+  const Mint = IDL.Record({
+    'to' : Account,
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(IDL.Nat64),
+    'amount' : IDL.Nat,
+  });
+  const Approve = IDL.Record({
+    'fee' : IDL.Opt(IDL.Nat),
+    'from' : Account,
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(IDL.Nat64),
+    'amount' : IDL.Nat,
+    'expected_allowance' : IDL.Opt(IDL.Nat),
+    'expires_at' : IDL.Opt(IDL.Nat64),
+    'spender' : Account,
+  });
+  const Transfer = IDL.Record({
+    'to' : Account,
+    'fee' : IDL.Opt(IDL.Nat),
+    'from' : Account,
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(IDL.Nat64),
+    'amount' : IDL.Nat,
+    'spender' : IDL.Opt(Account),
+  });
   const Transaction = IDL.Record({
-    'burn' : IDL.Opt(
-      IDL.Record({
-        'from' : Account,
-        'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
-        'created_at_time' : IDL.Opt(IDL.Nat64),
-        'amount' : IDL.Nat,
-      })
-    ),
+    'burn' : IDL.Opt(Burn),
     'kind' : IDL.Text,
-    'mint' : IDL.Opt(
-      IDL.Record({
-        'to' : Account,
-        'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
-        'created_at_time' : IDL.Opt(IDL.Nat64),
-        'amount' : IDL.Nat,
-      })
-    ),
+    'mint' : IDL.Opt(Mint),
+    'approve' : IDL.Opt(Approve),
     'timestamp' : IDL.Nat64,
-    'transfer' : IDL.Opt(
-      IDL.Record({
-        'to' : Account,
-        'fee' : IDL.Opt(IDL.Nat),
-        'from' : Account,
-        'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
-        'created_at_time' : IDL.Opt(IDL.Nat64),
-        'amount' : IDL.Nat,
-      })
-    ),
+    'transfer' : IDL.Opt(Transfer),
   });
   const TransactionRange = IDL.Record({
     'transactions' : IDL.Vec(Transaction),
@@ -138,6 +158,7 @@ export const idlFactory = ({ IDL }) => {
     ),
   });
   const Tokens = IDL.Nat;
+  const StandardRecord = IDL.Record({ 'url' : IDL.Text, 'name' : IDL.Text });
   const Timestamp = IDL.Nat64;
   const TransferArg = IDL.Record({
     'to' : Account,
@@ -164,6 +185,66 @@ export const idlFactory = ({ IDL }) => {
     'Ok' : BlockIndex,
     'Err' : TransferError,
   });
+  const AllowanceArgs = IDL.Record({
+    'account' : Account,
+    'spender' : Account,
+  });
+  const Allowance = IDL.Record({
+    'allowance' : IDL.Nat,
+    'expires_at' : IDL.Opt(IDL.Nat64),
+  });
+  const ApproveArgs = IDL.Record({
+    'fee' : IDL.Opt(IDL.Nat),
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'from_subaccount' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(IDL.Nat64),
+    'amount' : IDL.Nat,
+    'expected_allowance' : IDL.Opt(IDL.Nat),
+    'expires_at' : IDL.Opt(IDL.Nat64),
+    'spender' : Account,
+  });
+  const ApproveError = IDL.Variant({
+    'GenericError' : IDL.Record({
+      'message' : IDL.Text,
+      'error_code' : IDL.Nat,
+    }),
+    'TemporarilyUnavailable' : IDL.Null,
+    'Duplicate' : IDL.Record({ 'duplicate_of' : IDL.Nat }),
+    'BadFee' : IDL.Record({ 'expected_fee' : IDL.Nat }),
+    'AllowanceChanged' : IDL.Record({ 'current_allowance' : IDL.Nat }),
+    'CreatedInFuture' : IDL.Record({ 'ledger_time' : IDL.Nat64 }),
+    'TooOld' : IDL.Null,
+    'Expired' : IDL.Record({ 'ledger_time' : IDL.Nat64 }),
+    'InsufficientFunds' : IDL.Record({ 'balance' : IDL.Nat }),
+  });
+  const ApproveResult = IDL.Variant({ 'Ok' : IDL.Nat, 'Err' : ApproveError });
+  const TransferFromArgs = IDL.Record({
+    'to' : Account,
+    'fee' : IDL.Opt(Tokens),
+    'spender_subaccount' : IDL.Opt(Subaccount),
+    'from' : Account,
+    'memo' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'created_at_time' : IDL.Opt(Timestamp),
+    'amount' : Tokens,
+  });
+  const TransferFromError = IDL.Variant({
+    'GenericError' : IDL.Record({
+      'message' : IDL.Text,
+      'error_code' : IDL.Nat,
+    }),
+    'TemporarilyUnavailable' : IDL.Null,
+    'InsufficientAllowance' : IDL.Record({ 'allowance' : Tokens }),
+    'BadBurn' : IDL.Record({ 'min_burn_amount' : Tokens }),
+    'Duplicate' : IDL.Record({ 'duplicate_of' : BlockIndex }),
+    'BadFee' : IDL.Record({ 'expected_fee' : Tokens }),
+    'CreatedInFuture' : IDL.Record({ 'ledger_time' : IDL.Nat64 }),
+    'TooOld' : IDL.Null,
+    'InsufficientFunds' : IDL.Record({ 'balance' : Tokens }),
+  });
+  const TransferFromResult = IDL.Variant({
+    'Ok' : BlockIndex,
+    'Err' : TransferFromError,
+  });
   return IDL.Service({
     'get_blocks' : IDL.Func([GetBlocksArgs], [GetBlocksResponse], []),
     'get_data_certificate' : IDL.Func([], [DataCertificate], []),
@@ -182,14 +263,17 @@ export const idlFactory = ({ IDL }) => {
       ),
     'icrc1_minting_account' : IDL.Func([], [IDL.Opt(Account)], []),
     'icrc1_name' : IDL.Func([], [IDL.Text], []),
-    'icrc1_supported_standards' : IDL.Func(
-        [],
-        [IDL.Vec(IDL.Record({ 'url' : IDL.Text, 'name' : IDL.Text }))],
-        [],
-      ),
+    'icrc1_supported_standards' : IDL.Func([], [IDL.Vec(StandardRecord)], []),
     'icrc1_symbol' : IDL.Func([], [IDL.Text], []),
     'icrc1_total_supply' : IDL.Func([], [Tokens], []),
     'icrc1_transfer' : IDL.Func([TransferArg], [TransferResult], []),
+    'icrc2_allowance' : IDL.Func([AllowanceArgs], [Allowance], []),
+    'icrc2_approve' : IDL.Func([ApproveArgs], [ApproveResult], []),
+    'icrc2_transfer_from' : IDL.Func(
+        [TransferFromArgs],
+        [TransferFromResult],
+        [],
+      ),
   });
 };
 export const init = ({ IDL }) => {
@@ -208,30 +292,40 @@ export const init = ({ IDL }) => {
     'SetTo' : Account,
     'Unset' : IDL.Null,
   });
+  const FeatureFlags = IDL.Record({ 'icrc2' : IDL.Bool });
   const UpgradeArgs = IDL.Record({
     'token_symbol' : IDL.Opt(IDL.Text),
-    'transfer_fee' : IDL.Opt(IDL.Nat64),
+    'transfer_fee' : IDL.Opt(IDL.Nat),
     'metadata' : IDL.Opt(IDL.Vec(IDL.Tuple(IDL.Text, MetadataValue))),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
     'change_fee_collector' : IDL.Opt(ChangeFeeCollector),
     'max_memo_length' : IDL.Opt(IDL.Nat16),
     'token_name' : IDL.Opt(IDL.Text),
+    'feature_flags' : IDL.Opt(FeatureFlags),
   });
   const InitArgs = IDL.Record({
+    'decimals' : IDL.Opt(IDL.Nat8),
     'token_symbol' : IDL.Text,
-    'transfer_fee' : IDL.Nat64,
+    'transfer_fee' : IDL.Nat,
     'metadata' : IDL.Vec(IDL.Tuple(IDL.Text, MetadataValue)),
     'minting_account' : Account,
-    'initial_balances' : IDL.Vec(IDL.Tuple(Account, IDL.Nat64)),
+    'initial_balances' : IDL.Vec(IDL.Tuple(Account, IDL.Nat)),
+    'maximum_number_of_accounts' : IDL.Opt(IDL.Nat64),
+    'accounts_overflow_trim_quantity' : IDL.Opt(IDL.Nat64),
     'fee_collector_account' : IDL.Opt(Account),
     'archive_options' : IDL.Record({
       'num_blocks_to_archive' : IDL.Nat64,
+      'max_transactions_per_response' : IDL.Opt(IDL.Nat64),
       'trigger_threshold' : IDL.Nat64,
       'max_message_size_bytes' : IDL.Opt(IDL.Nat64),
       'cycles_for_archive_creation' : IDL.Opt(IDL.Nat64),
       'node_max_memory_size_bytes' : IDL.Opt(IDL.Nat64),
       'controller_id' : IDL.Principal,
     }),
+    'max_memo_length' : IDL.Opt(IDL.Nat16),
     'token_name' : IDL.Text,
+    'feature_flags' : IDL.Opt(FeatureFlags),
   });
   const LedgerArg = IDL.Variant({
     'Upgrade' : IDL.Opt(UpgradeArgs),