Merge remote-tracking branch 'origin/feat/move-ledger-icp-features' i…

…nto feat/move-ledger-icp-features
dfinity · Oct 2, 2023 · fbfb3c2 · fbfb3c2
2 parents 6f8b7aa + f4de198
commit fbfb3c2
Showing 1 changed file with 176 additions and 77 deletions.
diff --git a/packages/ledger-icp/README.md b/packages/ledger-icp/README.md
@@ -55,135 +55,234 @@ const data = await metadata();
 
 <!-- TSDOC_START -->
 
-### :factory: IcrcLedgerCanister
+### :factory: ICP
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L27)
+We don't extend to keep `fromE8s` and `fromString` as backwards compatible.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/icp.ts#L14)
 
 #### 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)
+- [fromE8s](#gear-frome8s)
+- [fromString](#gear-fromstring)
+- [toE8s](#gear-toe8s)
+- [toProto](#gear-toproto)
 
-##### :gear: create
+##### :gear: fromE8s
 
-| Method   | Type                                                                   |
-| -------- | ---------------------------------------------------------------------- |
-| `create` | `(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister` |
+| Method    | Type                      |
+| --------- | ------------------------- |
+| `fromE8s` | `(amount: bigint) => ICP` |
 
-[: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/icp.ts#L20)
 
-##### :gear: metadata
+##### :gear: fromString
 
-The token metadata (name, symbol, etc.).
+Initialize from a string. Accepted formats:
 
-| Method     | Type                                                          |
-| ---------- | ------------------------------------------------------------- |
-| `metadata` | `(params: QueryParams) => Promise<IcrcTokenMetadataResponse>` |
+1234567.8901
+1'234'567.8901
+1,234,567.8901
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L42)
+| Method       | Type                                                |
+| ------------ | --------------------------------------------------- |
+| `fromString` | `(amount: string) => ICP or FromStringToTokenError` |
 
-##### :gear: transactionFee
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/icp.ts#L31)
 
-The ledger transaction fees.
+##### :gear: toE8s
 
-| Method           | Type                                       |
-| ---------------- | ------------------------------------------ |
-| `transactionFee` | `(params: QueryParams) => Promise<bigint>` |
+| Method  | Type           |
+| ------- | -------------- |
+| `toE8s` | `() => bigint` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L50)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/icp.ts#L39)
 
-##### :gear: balance
+##### :gear: toProto
 
-Returns the balance for a given account provided as owner and with optional subaccount.
+| Method    | Type                   |
+| --------- | ---------------------- |
+| `toProto` | `() => Promise<ICPTs>` |
 
-| Method    | Type                                         |
-| --------- | -------------------------------------------- |
-| `balance` | `(params: BalanceParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/icp.ts#L43)
 
-Parameters:
+### :factory: AccountIdentifier
 
-- `params`: The parameters to get the balance of an account.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L13)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L59)
+#### Methods
 
-##### :gear: transfer
+- [fromHex](#gear-fromhex)
+- [fromPrincipal](#gear-fromprincipal)
+- [toProto](#gear-toproto)
+- [toHex](#gear-tohex)
+- [toUint8Array](#gear-touint8array)
+- [toNumbers](#gear-tonumbers)
+- [toAccountIdentifierHash](#gear-toaccountidentifierhash)
+
+##### :gear: fromHex
+
+| Method    | Type                                 |
+| --------- | ------------------------------------ |
+| `fromHex` | `(hex: string) => AccountIdentifier` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L16)
+
+##### :gear: fromPrincipal
 
-Transfers tokens from the sender to the given account.
+| Method          | Type                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `fromPrincipal` | `({ principal, subAccount, }: { principal: Principal; subAccount?: SubAccount; }) => AccountIdentifier` |
 
-| Method     | Type                                          |
-| ---------- | --------------------------------------------- |
-| `transfer` | `(params: TransferParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L20)
 
-Parameters:
+##### :gear: toProto
 
-- `params`: The parameters to transfer tokens.
+| Method    | Type                               |
+| --------- | ---------------------------------- |
+| `toProto` | `() => Promise<AccountIdentifier>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L72)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L49)
 
-##### :gear: totalTokensSupply
+##### :gear: toHex
 
-Returns the total supply of tokens.
+| Method  | Type           |
+| ------- | -------------- |
+| `toHex` | `() => string` |
 
-| Method              | Type                                       |
-| ------------------- | ------------------------------------------ |
-| `totalTokensSupply` | `(params: QueryParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L57)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L88)
+##### :gear: toUint8Array
+
+| Method         | Type               |
+| -------------- | ------------------ |
+| `toUint8Array` | `() => Uint8Array` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L61)
+
+##### :gear: toNumbers
+
+| Method      | Type             |
+| ----------- | ---------------- |
+| `toNumbers` | `() => number[]` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L65)
+
+##### :gear: toAccountIdentifierHash
+
+| Method                    | Type                      |
+| ------------------------- | ------------------------- |
+| `toAccountIdentifierHash` | `() => AccountIdentifier` |
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L69)
+
+### :factory: SubAccount
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L76)
+
+#### Methods
 
-##### :gear: transferFrom
+- [fromBytes](#gear-frombytes)
+- [fromPrincipal](#gear-fromprincipal)
+- [fromID](#gear-fromid)
+- [toUint8Array](#gear-touint8array)
 
-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.
+##### :gear: fromBytes
 
-Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from
+| Method      | Type                                         |
+| ----------- | -------------------------------------------- |
+| `fromBytes` | `(bytes: Uint8Array) => SubAccount or Error` |
 
-| Method         | Type                                              |
-| -------------- | ------------------------------------------------- |
-| `transferFrom` | `(params: TransferFromParams) => Promise<bigint>` |
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L79)
 
-Parameters:
+##### :gear: fromPrincipal
 
-- `params`: The parameters to transfer tokens from to.
+| Method          | Type                                   |
+| --------------- | -------------------------------------- |
+| `fromPrincipal` | `(principal: Principal) => SubAccount` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L101)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L87)
 
-##### :gear: approve
+##### :gear: fromID
 
-This method entitles the `spender` to transfer token `amount` on behalf of the caller from account `{ owner = caller; subaccount = from_subaccount }`.
+| Method   | Type                         |
+| -------- | ---------------------------- |
+| `fromID` | `(id: number) => SubAccount` |
 
-Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L100)
 
-| Method    | Type                                         |
-| --------- | -------------------------------------------- |
-| `approve` | `(params: ApproveParams) => Promise<bigint>` |
+##### :gear: toUint8Array
 
-Parameters:
+| Method         | Type               |
+| -------------- | ------------------ |
+| `toUint8Array` | `() => Uint8Array` |
 
-- `params`: The parameters to approve.
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/account_identifier.ts#L112)
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ledger/src/ledger.canister.ts#L123)
+### :factory: LedgerCanister
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/nns/src/ledger.canister.ts#L32)
+
+#### Methods
+
+- [create](#gear-create)
+- [accountBalance](#gear-accountbalance)
+- [transactionFee](#gear-transactionfee)
+- [transfer](#gear-transfer)
+- [icrc1Transfer](#gear-icrc1transfer)
+
+##### :gear: create
+
+| 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 -->