From f4de1986a63d239c691a66b0d291c115815f889f Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 2 Oct 2023 08:36:57 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Documentation=20auto-update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/ledger-icp/README.md | 253 +++++++++++++++++++++++----------- 1 file changed, 176 insertions(+), 77 deletions(-) diff --git a/packages/ledger-icp/README.md b/packages/ledger-icp/README.md index 78a2652f..1723b3d8 100644 --- a/packages/ledger-icp/README.md +++ b/packages/ledger-icp/README.md @@ -55,135 +55,234 @@ const data = await metadata(); -### :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` | +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` | +| 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` | -| Method | Type | -| --------- | -------------------------------------------- | -| `balance` | `(params: BalanceParams) => Promise` | +[: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` | +[: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` | -[: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` | +[: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` | +[: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` | +##### :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` | + +[: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` | + +[: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` | -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` | +##### :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` | -[: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)