feat: copy ICP ledger-related features to new ledger-icp library

CHANGELOG.md

@@ -1,3 +1,14 @@
+# 2023-XX-YY
+
+## Release
+
+- nns `v2.0.0`
+- ledger-icp `v1.0.0`
+
+## Breaking Changes ⚠️
+
+- ICP ledger-related features have been relocated from `@dfinity/nns` to a new dedicated library called `@dfinity/ledger-icp`
+
 # 1.0.0 (2023-10-02)
 
 ## Release

README.md

@@ -10,6 +10,7 @@ The libraries are still in active development, and new features will incremental
 - [sns](/packages/sns): interacting with a Service Nervous System (SNS) project
 - [cmc](/packages/cmc): interfacing with the **cmc** canister of the IC
 - [ledger](/packages/ledger): interacting with ICRC compatible **ledgers**
+- [ledger-icp](/packages/ledger-icp): interfacing with the **ICP ledger**
 - [ckBTC](/packages/ckbtc): interfacing with **ckBTC**
 - [ic-management](/packages/ic-management): interfacing with the **IC management canister**
 - [utils](/packages/utils): a collection of utilities and constants

package.json

@@ -95,6 +95,18 @@
         "@dfinity/utils"
       ]
     },
+    {
+      "name": "@dfinity/ledger-icp",
+      "path": "./packages/ledger-icp/dist/index.js",
+      "limit": "15 kB",
+      "ignore": [
+        "@dfinity/agent",
+        "@dfinity/candid",
+        "@dfinity/principal",
+        "@dfinity/utils",
+        "@dfinity/nns-proto"
+      ]
+    },
     {
       "name": "@dfinity/nns",
       "path": "./packages/nns/dist/index.js",

packages/ledger-icp/README.md

@@ -24,7 +24,7 @@ npm i @dfinity/ledger-icp
 The bundle needs peer dependencies, be sure that following resources are available in your project as well.
 
 ```bash
-npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils
+npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils @dfinity/nns-proto
 ```
 
 ## Usage
@@ -55,135 +55,183 @@ const data = await metadata();
 
 <!-- TSDOC_START -->
 
-### :factory: IcrcLedgerCanister
+### :factory: AccountIdentifier
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L27)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L13)
 
 #### Methods
 
-- [create](#gear-create)
-- [metadata](#gear-metadata)
-- [transactionFee](#gear-transactionfee)
-- [balance](#gear-balance)
-- [transfer](#gear-transfer)
-- [totalTokensSupply](#gear-totaltokenssupply)
-- [transferFrom](#gear-transferfrom)
-- [approve](#gear-approve)
-- [allowance](#gear-allowance)
+- [fromHex](#gear-fromhex)
+- [fromPrincipal](#gear-fromprincipal)
+- [toProto](#gear-toproto)
+- [toHex](#gear-tohex)
+- [toUint8Array](#gear-touint8array)
+- [toNumbers](#gear-tonumbers)
+- [toAccountIdentifierHash](#gear-toaccountidentifierhash)
 
-##### :gear: create
+##### :gear: fromHex
 
-| Method   | Type                                                                   |
-| -------- | ---------------------------------------------------------------------- |
-| `create` | `(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister` |
+| Method    | Type                                 |
+| --------- | ------------------------------------ |
+| `fromHex` | `(hex: string) => AccountIdentifier` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L28)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L16)
 
-##### :gear: metadata
+##### :gear: fromPrincipal
 
-The token metadata (name, symbol, etc.).
+| Method          | Type                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `fromPrincipal` | `({ principal, subAccount, }: { principal: Principal; subAccount?: SubAccount; }) => AccountIdentifier` |
 
-| Method     | Type                                                          |
-| ---------- | ------------------------------------------------------------- |
-| `metadata` | `(params: QueryParams) => Promise<IcrcTokenMetadataResponse>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L20)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L42)
+##### :gear: toProto
 
-##### :gear: transactionFee
+| Method    | Type                               |
+| --------- | ---------------------------------- |
+| `toProto` | `() => Promise<AccountIdentifier>` |
 
-The ledger transaction fees.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L49)
 
-| Method           | Type                                       |
-| ---------------- | ------------------------------------------ |
-| `transactionFee` | `(params: QueryParams) => Promise<bigint>` |
+##### :gear: toHex
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L50)
+| Method  | Type           |
+| ------- | -------------- |
+| `toHex` | `() => string` |
 
-##### :gear: balance
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L57)
 
-Returns the balance for a given account provided as owner and with optional subaccount.
+##### :gear: toUint8Array
 
-| Method    | Type                                         |
-| --------- | -------------------------------------------- |
-| `balance` | `(params: BalanceParams) => Promise<bigint>` |
+| Method         | Type               |
+| -------------- | ------------------ |
+| `toUint8Array` | `() => Uint8Array` |
 
-Parameters:
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L61)
 
-- `params`: The parameters to get the balance of an account.
+##### :gear: toNumbers
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L59)
+| Method      | Type             |
+| ----------- | ---------------- |
+| `toNumbers` | `() => number[]` |
 
-##### :gear: transfer
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L65)
+
+##### :gear: toAccountIdentifierHash
 
-Transfers tokens from the sender to the given account.
+| Method                    | Type                      |
+| ------------------------- | ------------------------- |
+| `toAccountIdentifierHash` | `() => AccountIdentifier` |
 
-| Method     | Type                                          |
-| ---------- | --------------------------------------------- |
-| `transfer` | `(params: TransferParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L69)
 
-Parameters:
+### :factory: SubAccount
 
-- `params`: The parameters to transfer tokens.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L76)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L72)
+#### Methods
 
-##### :gear: totalTokensSupply
+- [fromBytes](#gear-frombytes)
+- [fromPrincipal](#gear-fromprincipal)
+- [fromID](#gear-fromid)
+- [toUint8Array](#gear-touint8array)
 
-Returns the total supply of tokens.
+##### :gear: fromBytes
 
-| Method              | Type                                       |
-| ------------------- | ------------------------------------------ |
-| `totalTokensSupply` | `(params: QueryParams) => Promise<bigint>` |
+| Method      | Type                                         |
+| ----------- | -------------------------------------------- |
+| `fromBytes` | `(bytes: Uint8Array) => SubAccount or Error` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L88)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L79)
 
-##### :gear: transferFrom
+##### :gear: fromPrincipal
 
-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.
+| Method          | Type                                   |
+| --------------- | -------------------------------------- |
+| `fromPrincipal` | `(principal: Principal) => SubAccount` |
 
-Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L87)
 
-| Method         | Type                                              |
-| -------------- | ------------------------------------------------- |
-| `transferFrom` | `(params: TransferFromParams) => Promise<bigint>` |
+##### :gear: fromID
 
-Parameters:
+| Method   | Type                         |
+| -------- | ---------------------------- |
+| `fromID` | `(id: number) => SubAccount` |
 
-- `params`: The parameters to transfer tokens from to.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L100)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L101)
+##### :gear: toUint8Array
 
-##### :gear: approve
+| Method         | Type               |
+| -------------- | ------------------ |
+| `toUint8Array` | `() => Uint8Array` |
 
-This method entitles the `spender` to transfer token `amount` on behalf of the caller from account `{ owner = caller; subaccount = from_subaccount }`.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L112)
 
-Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve
+### :factory: LedgerCanister
 
-| Method    | Type                                         |
-| --------- | -------------------------------------------- |
-| `approve` | `(params: ApproveParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L32)
 
-Parameters:
+#### Methods
 
-- `params`: The parameters to approve.
+- [create](#gear-create)
+- [accountBalance](#gear-accountbalance)
+- [transactionFee](#gear-transactionfee)
+- [transfer](#gear-transfer)
+- [icrc1Transfer](#gear-icrc1transfer)
+
+##### :gear: create
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L123)
+| Method   | Type                                                  |
+| -------- | ----------------------------------------------------- |
+| `create` | `(options?: LedgerCanisterOptions) => LedgerCanister` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L43)
+
+##### :gear: accountBalance
+
+Returns the balance of the specified account identifier.
+
+If `certified` is true, the request is fetched as an update call, otherwise
+it is fetched using a query call.
+
+| Method           | Type                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `accountBalance` | `({ accountIdentifier, certified, }: { accountIdentifier: AccountIdentifier; certified?: boolean; }) => Promise<bigint>` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L75)
+
+##### :gear: transactionFee
+
+Returns the transaction fee of the ledger canister
+
+| Method           | Type                    |
+| ---------------- | ----------------------- |
+| `transactionFee` | `() => Promise<bigint>` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L99)
+
+##### :gear: transfer
 
-##### :gear: allowance
+Transfer ICP from the caller to the destination `accountIdentifier`.
+Returns the index of the block containing the tx if it was successful.
 
-Returns the token allowance that the `spender` account can transfer from the specified `account`, and the expiration time for that allowance, if any.
+| Method     | Type                                            |
+| ---------- | ----------------------------------------------- |
+| `transfer` | `(request: TransferRequest) => Promise<bigint>` |
 
-Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L112)
 
-| Method      | Type                                              |
-| ----------- | ------------------------------------------------- |
-| `allowance` | `(params: AllowanceParams) => Promise<Allowance>` |
+##### :gear: icrc1Transfer
 
-Parameters:
+Transfer ICP from the caller to the destination `Account`.
+Returns the index of the block containing the tx if it was successful.
 
-- `params`: The parameters to call the allowance.
+| Method          | Type                                                 |
+| --------------- | ---------------------------------------------------- |
+| `icrc1Transfer` | `(request: Icrc1TransferRequest) => Promise<bigint>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L145)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L142)
 
 <!-- TSDOC_END -->
 

packages/ledger-icp/package.json

@@ -40,6 +40,7 @@
   "peerDependencies": {
     "@dfinity/agent": "^0.19.2",
     "@dfinity/candid": "^0.19.2",
+    "@dfinity/nns-proto": "^1.0.0",
     "@dfinity/principal": "^0.19.2",
     "@dfinity/utils": "^1.0.0"
   }