UNPKG

@near-js/accounts

Version:

Classes encapsulating account-specific functionality

507 lines (504 loc) 23.4 kB
import * as _near_js_transactions from '@near-js/transactions'; import { Action, SignedTransaction, DelegateAction, SignedDelegate } from '@near-js/transactions'; import { PublicKey } from '@near-js/crypto'; import { Provider } from '@near-js/providers'; import { TxExecutionStatus, AccessKeyView, AccessKeyList, ContractCodeView, ContractStateView, FinalExecutionOutcome, BlockReference, AccessKeyInfoView, AccountView } from '@near-js/types'; import { Signer, SignedMessage } from '@near-js/signers'; import { C as Connection, a as ChangeFunctionCallOptions, V as ViewFunctionCallOptions } from './connection-BbhZTxD7.js'; import { NativeToken, FungibleToken } from '@near-js/tokens'; declare const DEFAULT_WAIT_STATUS: TxExecutionStatus; interface AccountState { balance: { total: bigint; usedOnStorage: bigint; locked: bigint; available: bigint; }; storageUsage: number; codeHash: string; } interface AccountBalance { total: string; stateStaked: string; staked: string; available: string; } interface AccountAuthorizedApp { contractId: string; amount: string; publicKey: string; } /** * Options used to initiate sining and sending transactions */ interface SignAndSendTransactionOptions { receiverId: string; actions: Action[]; /** * Metadata to send the NEAR Wallet if using it to sign transactions. * @see RequestSignTransactionsOptions */ walletMeta?: string; /** * Callback url to send the NEAR Wallet if using it to sign transactions. * @see RequestSignTransactionsOptions */ walletCallbackUrl?: string; returnError?: boolean; } interface StakedBalance { validatorId: string; amount?: string; error?: string; } interface ActiveDelegatedStakeBalance { stakedValidators: StakedBalance[]; failedValidators: StakedBalance[]; total: bigint | string; } interface SignedDelegateOptions { actions: Action[]; blockHeightTtl: number; receiverId: string; } /** * This class allows to access common account information. * If a {@link Signer} is provider, then the account can * be used to perform all common actions such as * transferring tokens and calling functions */ declare class Account { readonly accountId: string; readonly provider: Provider; private signer?; constructor(accountId: string, provider: Provider, signer?: Signer); /** * Allows to set the signer used to control the account * * @param signer holds the private key and can sign Transactions */ setSigner(signer: Signer): void; getSigner(): Signer | undefined; /** * Returns an overview of the account's state, including the account's * balance, storage usage, and code hash */ getState(): Promise<AccountState>; /** * Calls {@link Provider.viewAccessKey} to retrieve information for a * specific key in the account */ getAccessKey(publicKey: PublicKey | string): Promise<AccessKeyView>; /** * Calls {@link Provider.viewAccessKeyList} to retrieve the account's keys */ getAccessKeyList(): Promise<AccessKeyList>; /** * Calls {@link Provider.viewContractCode} to retrieve the account's * contract code and its hash */ getContractCode(): Promise<ContractCodeView>; /** * Calls {@link Provider.viewContractState} to retrieve the keys and values * stored on the account's contract */ getContractState(prefix?: string): Promise<ContractStateView>; /** * Create a transaction that can be later signed with a {@link Signer} * * @param receiverId Account against which to perform the actions * @param actions Actions to perform * @param publicKey The public part of the key that will be used to sign the transaction */ createTransaction(receiverId: string, actions: Action[], publicKey: PublicKey | string): Promise<_near_js_transactions.Transaction>; /** * Create a signed transaction ready to be broadcast by a {@link Provider} */ createSignedTransaction(receiverId: string, actions: Action[]): Promise<SignedTransaction>; /** * Create a meta transaction ready to be signed by a {@link Signer} * * @param receiverId NEAR account receiving the transaction * @param actions list of actions to perform as part of the meta transaction * @param blockHeightTtl number of blocks after which a meta transaction will expire if not processed */ createMetaTransaction(receiverId: string, actions: Action[], blockHeightTtl: number, publicKey: PublicKey | string): Promise<DelegateAction>; /** * Create a signed MetaTransaction that can be broadcasted to a relayer * * @param receiverId NEAR account receiving the transaction * @param actions list of actions to perform as part of the meta transaction * @param blockHeightTtl number of blocks after which a meta transaction will expire if not processed */ createSignedMetaTransaction(receiverId: string, actions: Action[], blockHeightTtl?: number): Promise<[Uint8Array, SignedDelegate]>; /** * Creates a transaction, signs it and broadcast it to the network * * @param receiverId The NEAR account ID of the transaction receiver. * @param actions The list of actions to be performed in the transaction. * @param throwOnFailure Whether to throw an error if the transaction fails. * @returns {Promise<FinalExecutionOutcome>} A promise that resolves to the final execution outcome of the transaction. * */ signAndSendTransaction({ receiverId, actions, waitUntil, throwOnFailure, }: { receiverId: string; actions: Action[]; waitUntil?: TxExecutionStatus; throwOnFailure?: boolean; }): Promise<FinalExecutionOutcome>; signAndSendTransactions({ transactions, waitUntil, throwOnFailure, }: { transactions: { receiverId: string; actions: Action[]; }[]; waitUntil?: TxExecutionStatus; throwOnFailure?: boolean; }): Promise<FinalExecutionOutcome[]>; /** * Creates a new NEAR account with a given ID and public key. * * This method can create two types of accounts: * * 1. Top-level accounts of the form `name.tla` (e.g., `bob.near`): * * 2. Sub-accounts of the current account (e.g., `sub.ana.near`): * - The new account ID must end with the current account ID * - Example: If your account is `ana.near`, you can create `sub.ana.near` * * @param newAccountId the new account to create (e.g. bob.near or sub.ana.near) * @param publicKey the public part of the key that will control the account * @param nearToTransfer how much NEAR to transfer to the account in yoctoNEAR (default: 0) * */ createAccount(newAccountId: string, publicKey: PublicKey | string, nearToTransfer?: bigint | string | number): Promise<FinalExecutionOutcome>; /** * Creates a sub account of this account. For example, if the account is * ana.near, you can create sub.ana.near. * * @param accountOrPrefix a prefix (e.g. `sub`) or the full sub-account (`sub.ana.near`) * @param publicKey the public part of the key that will control the account * @param nearToTransfer how much NEAR to transfer to the account (default: 0) * */ createSubAccount(accountOrPrefix: string, publicKey: PublicKey | string, nearToTransfer?: bigint | string | number): Promise<FinalExecutionOutcome>; /** * Deletes the account, transferring all remaining NEAR to a beneficiary * account * * Important: Deleting an account does not transfer FTs or NFTs * * @param beneficiaryId Will receive the account's remaining balance */ deleteAccount(beneficiaryId: string): Promise<FinalExecutionOutcome>; /** * Deploy a smart contract in the account * * @param code The compiled contract code bytes */ deployContract(code: Uint8Array): Promise<FinalExecutionOutcome>; /** * Deploy a global contract that can be reused by multiple accounts * * @param code The compiled contract code bytes * @param deployMode Deploy mode - "codeHash" for immutable contracts, "accountId" for updateable contracts */ deployGlobalContract(code: Uint8Array, deployMode: "codeHash" | "accountId"): Promise<FinalExecutionOutcome>; /** * Use a previously deployed global contract on this account * * @param contractIdentifier The global contract identifier - either { accountId: string } or { codeHash: string | Uint8Array } */ useGlobalContract(contractIdentifier: { accountId: string; } | { codeHash: string | Uint8Array; }): Promise<FinalExecutionOutcome>; /** * * @param options * @param options.publicKey The key to add to the account * @param options.contractId The contract that this key can call * @param options.methodNames The methods this key is allowed to call * @param options.allowance The amount of NEAR this key can expend in gas * @returns */ addFunctionCallAccessKey({ publicKey, contractId, methodNames, allowance, }: { publicKey: PublicKey | string; contractId: string; methodNames: string[]; allowance: bigint | string | number; }): Promise<FinalExecutionOutcome>; /** * Add a full access key to the account * * @param publicKey The public key to be added * @returns {Promise<FinalExecutionOutcome>} */ addFullAccessKey(publicKey: PublicKey | string): Promise<FinalExecutionOutcome>; /** * @param publicKey The public key to be deleted * @returns {Promise<FinalExecutionOutcome>} */ deleteKey(publicKey: PublicKey | string): Promise<FinalExecutionOutcome>; /** * Call a function on a smart contract and return parsed transaction result * * @param options * @param options.contractId The contract in which to call the function * @param options.methodName The method that will be called * @param options.args Arguments, either as a valid JSON Object or a raw Uint8Array * @param options.deposit (optional) Amount of NEAR Tokens to attach to the call (default 0) * @param options.gas (optional) Amount of GAS to use attach to the call (default 30TGas) * @param options.waitUntil (optional) Transaction finality to wait for (default INCLUDED_FINAL) * @returns */ callFunction(params: { contractId: string; methodName: string; args: Uint8Array | Record<string, any>; deposit?: bigint | string | number; gas?: bigint | string | number; waitUntil?: TxExecutionStatus; }): Promise<object | string | number>; /** * Call a function on a smart contract and return raw transaction outcome * * @param options * @param options.contractId The contract in which to call the function * @param options.methodName The method that will be called * @param options.args Arguments, either as a valid JSON Object or a raw Uint8Array * @param options.deposit (optional) Amount of NEAR Tokens to attach to the call (default 0) * @param options.gas (optional) Amount of GAS to use attach to the call (default 30TGas) * @param options.waitUntil (optional) Transaction finality to wait for (default INCLUDED_FINAL) * @returns {FinalExecutionOutcome} */ callFunctionRaw({ contractId, methodName, args, deposit, gas, waitUntil, }: { contractId: string; methodName: string; args: Uint8Array | Record<string, any>; deposit?: bigint | string | number; gas?: bigint | string | number; waitUntil?: TxExecutionStatus; }): Promise<FinalExecutionOutcome>; /** * This function simply calls the `signNep413Message` method of the Signer * * @param options * @param options.message The message to be signed (e.g. "authenticating") * @param options.recipient Who will receive the message (e.g. auth.app.com) * @param options.nonce A challenge sent by the recipient * @param options.callbackUrl (optional) Deprecated parameter used only by browser wallets * @returns */ signNep413Message({ message, recipient, nonce, callbackUrl, }: { message: string; recipient: string; nonce: Uint8Array; callbackUrl?: string; }): Promise<SignedMessage>; /** * * @param token The token to check the balance of. Defaults to Native NEAR. * @returns The available balance of the account in units (e.g. yoctoNEAR). */ getBalance(token?: NativeToken | FungibleToken): Promise<bigint>; /** * Transfers a token to the specified receiver. * * Supports sending either the native NEAR token or any supported Fungible Token (FT). * * @param amount - The amount of tokens to transfer in units (e.g. yoctoNEAR). * @param receiverId - The NEAR account ID of the receiver. * @param token - The token to transfer. Defaults to Native NEAR. * */ transfer({ receiverId, amount, token, }: { receiverId: string; amount: bigint | string | number; token?: NativeToken | FungibleToken; }): Promise<FinalExecutionOutcome>; /** * @deprecated please use {@link Account.createSignedMetaTransaction} instead * * Compose and sign a SignedDelegate action to be executed in a transaction on behalf of this Account instance * * @param options Options for the transaction. * @param options.actions Actions to be included in the meta transaction * @param options.blockHeightTtl Number of blocks past the current block height for which the SignedDelegate action may be included in a meta transaction * @param options.receiverId Receiver account of the meta transaction */ signedDelegate({ actions, blockHeightTtl, receiverId, }: SignedDelegateOptions): Promise<SignedDelegate>; /** * @deprecated, accounts no longer use Connections since it's deprecated too */ getConnection(): Connection; /** @hidden */ private validateArgs; /** * @deprecated please use {@link callFunction} instead * * Execute a function call. * @param options The options for the function call. * @param options.contractId The NEAR account ID of the smart contract. * @param options.methodName The name of the method to be called on the smart contract. * @param options.args The arguments to be passed to the method. * @param options.gas The maximum amount of gas to be used for the function call. * @param options.attachedDeposit The amount of NEAR tokens to be attached to the function call. * @param options.walletMeta Metadata for wallet integration. * @param options.walletCallbackUrl The callback URL for wallet integration. * @param options.stringify A function to convert input arguments into bytes array * @returns {Promise<FinalExecutionOutcome>} A promise that resolves to the final execution outcome of the function call. */ functionCall({ contractId, methodName, args, gas, attachedDeposit, walletMeta, walletCallbackUrl, stringify, }: ChangeFunctionCallOptions): Promise<FinalExecutionOutcome>; /** * @deprecated use instead {@link Provider.viewTransactionStatus} */ getTransactionStatus(txHash: string | Uint8Array): Promise<FinalExecutionOutcome>; /** * @deprecated use ${@link createSignedTransaction} * Create a signed transaction which can be broadcast to the network * @param receiverId NEAR account receiving the transaction * @param actions list of actions to perform as part of the transaction * @see {@link "@near-js/providers".json-rpc-provider.JsonRpcProvider.sendTransaction | JsonRpcProvider.sendTransaction} */ signTransaction(receiverId: string, actions: Action[], opts?: { signer: Signer; }): Promise<[Uint8Array, SignedTransaction]>; /** * @deprecated instead please create a transaction with * the actions bellow and broadcast it to the network * 1. createAccount * 2. transfer some tokens * 3. deployContract * 4. (optional) addKey * 5. (optional) functionCall to an initialization function * * Create a new account and deploy a contract to it * @param contractId NEAR account where the contract is deployed * @param publicKey The public key to add to the created contract account * @param data The compiled contract code * @param amount of NEAR to transfer to the created contract account. Transfer enough to pay for storage https://docs.near.org/docs/concepts/storage-staking */ createAndDeployContract(contractId: string, publicKey: string | PublicKey, data: Uint8Array, amount: bigint): Promise<Account>; /** * @deprecated please instead use {@link transfer} * * @param receiverId NEAR account receiving Ⓝ * @param amount Amount to send in yoctoⓃ */ sendMoney(receiverId: string, amount: bigint): Promise<FinalExecutionOutcome>; /** * @deprecated please instead use {@link signAndSendTransaction} * * Sign a transaction to perform a list of actions and broadcast it using the RPC API. * @see {@link "@near-js/providers".json-rpc-provider.JsonRpcProvider | JsonRpcProvider } * * @param options The options for signing and sending the transaction. * @param options.receiverId The NEAR account ID of the transaction receiver. * @param options.actions The list of actions to be performed in the transaction. * @param options.returnError Whether to return an error if the transaction fails. * @returns {Promise<FinalExecutionOutcome>} A promise that resolves to the final execution outcome of the transaction. * */ signAndSendTransactionLegacy({ receiverId, actions, returnError }: SignAndSendTransactionOptions, opts?: { signer: Signer; }): Promise<FinalExecutionOutcome>; /** @hidden */ accessKeyByPublicKeyCache: { [key: string]: AccessKeyView; }; /** * @deprecated, accounts will no longer handle keystores * * Finds the {@link AccessKeyView} associated with the accounts {@link PublicKey} stored in the {@link "@near-js/keystores".keystore.KeyStore | Keystore}. * * @param receiverId currently unused * @param actions currently unused * @returns `{ publicKey PublicKey; accessKey: AccessKeyView }` */ findAccessKey(receiverId: string, actions: Action[]): Promise<{ publicKey: PublicKey; accessKey: AccessKeyView; }>; /** * @deprecated please use {@link addFullAccessKey} or {@link addFunctionAccessKey} * * @see [https://docs.near.org/concepts/basics/accounts/access-keys](https://docs.near.org/concepts/basics/accounts/access-keys) * @todo expand this API to support more options. * @param publicKey A public key to be associated with the contract * @param contractId NEAR account where the contract is deployed * @param methodNames The method names on the contract that should be allowed to be called. Pass null for no method names and '' or [] for any method names. * @param amount Payment in yoctoⓃ that is sent to the contract during this function call */ addKey(publicKey: string | PublicKey, contractId?: string, methodNames?: string | string[], amount?: bigint): Promise<FinalExecutionOutcome>; /** * @deprecated please use {@link Provider.callFunction} instead * * Invoke a contract view function using the RPC API. * @see [https://docs.near.org/api/rpc/contracts#call-a-contract-function](https://docs.near.org/api/rpc/contracts#call-a-contract-function) * * @param options Function call options. * @param options.contractId NEAR account where the contract is deployed * @param options.methodName The view-only method (no state mutations) name on the contract as it is written in the contract code * @param options.args Any arguments to the view contract method, wrapped in JSON * @param options.parse Parse the result of the call. Receives a Buffer (bytes array) and converts it to any object. By default result will be treated as json. * @param options.stringify Convert input arguments into a bytes array. By default the input is treated as a JSON. * @param options.blockQuery specifies which block to query state at. By default returns last DEFAULT_FINALITY block (i.e. not necessarily finalized). * @returns {Promise<any>} */ viewFunction(options: ViewFunctionCallOptions): Promise<any>; /** * @deprecated please use {@link getContractState} instead * * Returns the state (key value pairs) of this account's contract based on the key prefix. * Pass an empty string for prefix if you would like to return the entire state. * @see [https://docs.near.org/api/rpc/contracts#view-contract-state](https://docs.near.org/api/rpc/contracts#view-contract-state) * * @param prefix allows to filter which keys should be returned. Empty prefix means all keys. String prefix is utf-8 encoded. * @param blockQuery specifies which block to query state at. By default returns last DEFAULT_FINALITY block (i.e. not necessarily finalized). */ viewState(prefix: string | Uint8Array, blockQuery?: BlockReference): Promise<Array<{ key: Buffer; value: Buffer; }>>; /** * @deprecated please use {@link getAccessKeyList} instead * * Get all access keys for the account * @see [https://docs.near.org/api/rpc/access-keys#view-access-key-list](https://docs.near.org/api/rpc/access-keys#view-access-key-list) * */ getAccessKeys(): Promise<AccessKeyInfoView[]>; /** * @deprecated * * Returns a list of authorized apps * @todo update the response value to return all the different keys, not just app keys. * */ getAccountDetails(): Promise<{ authorizedApps: AccountAuthorizedApp[]; }>; /** * @deprecated please use {@link getState} instead * * Returns basic NEAR account information via the `view_account` RPC query method * @see [https://docs.near.org/api/rpc/contracts#view-account](https://docs.near.org/api/rpc/contracts#view-account) */ state(): Promise<AccountView>; /** * @deprecated please use {@link getState} instead * */ getAccountBalance(): Promise<AccountBalance>; /** * Returns the NEAR tokens balance and validators of a given account that is delegated to the staking pools that are part of the validators set in the current epoch. * * @deprecated * * NOTE: If the tokens are delegated to a staking pool that is currently on pause or does not have enough tokens to participate in validation, they won't be accounted for. * @returns {Promise<ActiveDelegatedStakeBalance>} */ getActiveDelegatedStakeBalance(): Promise<ActiveDelegatedStakeBalance>; } export { Account, type AccountAuthorizedApp, type AccountBalance, type AccountState, DEFAULT_WAIT_STATUS, type SignAndSendTransactionOptions };