supra-ts-sdk - v2.0.0
    Preparing search index...

    Class Account

    The Account class provides methods for querying the state of an account.

    Hierarchy (View Summary)

    Index
    • The constructor function takes a NetworkConfig object as a parameter and assigns it to the networkInformation property.

      Parameters

      • networkInformation: NetworkConfig

        A NetworkConfig object that contains information about the network on which the SupraClient is running.

      Returns Account

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
    • Check whether given account exists onchain or not

      Parameters

      Returns Promise<boolean>

      true if account exists otherwise false. The node reports an absent account with HTTP 404 on v12 and HTTP 400 with a "Resource not found" message on v11; both give false.

      Any other failure, such as an unreachable node, a timeout, a rate limit (HTTP 429) or a node fault (HTTP 5xx), is thrown and does not mean the account is absent.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const isAccountExists = await supra.account.isAccountExists({ accountAddress });
      console.log(isAccountExists);
      }

      runExample().catch(console.error);
    • Queries the current state of an account, including its sequence number and authentication key.

      Parameters

      Returns Promise<AccountData>

      A Promise that resolves to an AccountData object containing the sequence number and authentication key of the account.

      For an account that does not exist: HTTP 404 on v12, HTTP 400 on v11. See "HTTP status codes by node version" in the README.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountData = await supra.account.getAccountInfo({ accountAddress: accountAddress });
      console.log(accountData);
      }

      runExample().catch(console.error);
    • Queries the modules of an account.

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: { count?: number; start?: string };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: { count?: number; start?: string }
          • Optionalcount?: number

            The number of modules to return.

          • Optionalstart?: string

            The cursor of the previous page. Omit it, or pass undefined, for the first page.

      Returns Promise<PaginatedResponse<MoveModuleBytecode[]>>

      A Promise that resolves to an array of MoveModuleBytecode objects representing the modules of the account with optional cursor. cursor is undefined when there are no more modules; see PaginatedResponse.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const {response: accountModules, cursor} = await supra.account.getAccountModules({ accountAddress: accountAddress });
      console.log(accountModules);
      }

      runExample().catch(console.error);
    • Queries a specific module of an account.

      Parameters

      • args: { accountAddress: AccountAddressInput; moduleName: string }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • moduleName: string

          The name of the module to query.

      Returns Promise<MoveModuleBytecode>

      A Promise that resolves to a MoveModuleBytecode object representing the module of the account.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountModule = await supra.account.getAccountModule({ accountAddress: accountAddress, moduleName: "module_name" });
      console.log(accountModule);
      }

      runExample().catch(console.error);
    • Queries the resources of an account.

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: { count?: number; start?: string };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: { count?: number; start?: string }
          • Optionalcount?: number

            The number of resources to return.

          • Optionalstart?: string

            The cursor of the previous page. Omit it, or pass undefined, for the first page.

      Returns Promise<PaginatedResponse<MoveResource[]>>

      A Promise that resolves to an array of MoveResource objects representing the resources of the account with optional cursor. cursor is undefined when there are no more resources; see PaginatedResponse.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const {response: accountResources, cursor} = await supra.account.getAccountResources({ accountAddress: accountAddress });
      console.log(accountResources);
      }

      runExample().catch(console.error);
    • Queries a specific resource of an account.

      Type Parameters

      • T extends object

        The type of the resource to be returned.

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            resourceType: `${string}::${string}::${string}`;
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • resourceType: `${string}::${string}::${string}`

          The type of the resource to query.

      Returns Promise<MoveResource<T>>

      A Promise that resolves to a MoveResource object representing the resource of the account.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountResource = await supra.account.getAccountResource({ accountAddress: accountAddress, resourceType: "0x1::account::Account" });
      console.log(accountResource);
      }

      runExample().catch(console.error);
    • Queries the transactions of an account.

      Type Parameters

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: {
                count?: number;
                start?: string | number | bigint;
                ascending?: boolean;
            };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: { count?: number; start?: string | number | bigint; ascending?: boolean }
          • Optionalcount?: number

            The number of transactions to return.

          • Optionalstart?: string | number | bigint

            The sequence number to start from, inclusive in both orders, or the cursor of the previous page. Omit it for the most recent transactions (descending) or the first ones (ascending).

          • Optionalascending?: boolean

            Whether to return the transactions in ascending order.

      Returns Promise<PaginatedResponse<T[]>>

      A Promise that resolves to an array of TransactionResponse objects representing the transactions of the account with optional cursor. The items are user transactions.

      • options.count defaults to 20 on the node; the SDK rejects a value outside 1 to 100.
      • The node pages this feed by sequence number and sends no x-supra-cursor header. The SDK computes cursor as the sequence number after the last transaction of the page in the requested order, so it is passed back as start like the cursor of the other feeds. It is undefined when the page is empty, or ends at sequence number 0 in descending order.
      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const {response: accountTransactions, cursor} = await supra.account.getAccountTransactions({ accountAddress: accountAddress });
      console.log(accountTransactions);
      }

      runExample().catch(console.error);
    • Queries the coin transactions of an account: the transactions that touched a CoinStore of the account. It does not list SUPRA held in a primary fungible store (a chain created from the supra_node_v12.0.0 genesis, such as Devnet, holds all SUPRA there), so the page is empty for an account whose only movements are of that SUPRA. For those, use Account.getAccountFaTransactions on the account's primary store (all networks) or Account.getAccountHistory (nodes from supra_node_v12.0.0).

      Type Parameters

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: {
                count?: number;
                start?: string;
                ascending?: boolean;
                type?: TransactionQueryType;
            };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: {
              count?: number;
              start?: string;
              ascending?: boolean;
              type?: TransactionQueryType;
          }
          • Optionalcount?: number

            The number of transactions to return.

          • Optionalstart?: string

            The cursor of the previous page, exclusive. Omit it, or pass undefined, for the first page.

          • Optionalascending?: boolean

            Whether to return the transactions in ascending order.

          • Optionaltype?: TransactionQueryType

            Return only transactions of this type. "settlement" requires a node from v12 onwards; older nodes reject it with HTTP 400. A page filtered by type can be empty and still carry a cursor.

      Returns Promise<PaginatedResponse<T[]>>

      A Promise that resolves to an array of TransactionResponse objects representing the coin transactions of the account with optional cursor. Items can be of any txn_type, including settlement items, which have no header, payload or authenticator; narrow on txn_type before reading them. cursor is undefined when there are no more transactions; see PaginatedResponse.

      • options.count defaults to 20 on the node; the SDK rejects a value outside 1 to 100.
      • An empty page with the cursor "0" ends the feed, as v11 nodes end it, except for the first request of an ascending read with a type filter: block 0 has timestamp 0, so the cursor "0" can mean that the page scanned only a genesis row that the filter excluded. The SDK then returns "0", and the request with start "0" continues the feed or ends it, so the rule costs at most one more request.
      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const {response: accountCoinTransactions , cursor} = await supra.account.getAccountCoinTransactions({ accountAddress: accountAddress });
      console.log(accountCoinTransactions);
      }

      runExample().catch(console.error);
    • Queries the fungible asset transactions of one fungible store: the finalized transactions that withdrew from or deposited to that store. The feed lists the movements of the store only; an account address returns an empty page. Derive an account's primary store with Account.getPrimaryStoreAddress. To list everything that concerns an account, use Account.getAccountHistory (nodes from supra_node_v12.0.0).

      Type Parameters

      Parameters

      • args: {
            storeAddress: AccountAddressInput;
            options?: {
                count?: number;
                start?: string;
                ascending?: boolean;
                type?: TransactionQueryType;
            };
        }
        • storeAddress: AccountAddressInput

          The address of the fungible store to query, for example the result of Account.getPrimaryStoreAddress. It is not the address of the account that owns the store.

        • Optionaloptions?: {
              count?: number;
              start?: string;
              ascending?: boolean;
              type?: TransactionQueryType;
          }
          • Optionalcount?: number

            The number of transactions to return.

          • Optionalstart?: string

            The cursor of the previous page, exclusive. Omit it, or pass undefined, for the first page.

          • Optionalascending?: boolean

            Whether to return the transactions in ascending order.

          • Optionaltype?: TransactionQueryType

            Return only transactions of this type. "settlement" requires a node from v12 onwards; older nodes reject it with HTTP 400. A page filtered by type can be empty and still carry a cursor.

      Returns Promise<PaginatedResponse<T[]>>

      A Promise that resolves to the transactions of the store with an optional cursor. Items can be of any txn_type; narrow on txn_type before reading header, payload or authenticator. cursor is undefined when there are no more transactions; see PaginatedResponse.

      • options.count defaults to 20 on the node; the SDK rejects a value outside 1 to 100.
      • Mainnet, Testnet and Devnet nodes serve this feed.
      • An empty page with the cursor "0" ends the feed, as v11 nodes end it, except for the first request of an ascending read with a type filter: block 0 has timestamp 0, so a store funded at genesis has a row with the cursor 0, and the cursor "0" can mean that the page scanned only that row and the filter excluded it. The SDK then returns "0", and the request with start "0" continues the feed or ends it, so the rule costs at most one more request.
      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const storeAddress = await supra.account.getPrimaryStoreAddress({ accountAddress: "0x1" });
      const { response: faTransactions, cursor } = await supra.account.getAccountFaTransactions({ storeAddress });
      console.log(faTransactions.length, cursor);
      }

      runExample().catch(console.error);
    • Returns the address of the primary fungible store of an account for a fungible asset, by calling 0x1::primary_fungible_store::primary_store_address. The address is computed from the owner and the metadata and does not show that the store exists. It is the storeAddress that Account.getAccountFaTransactions takes.

      Parameters

      Returns Promise<string>

      A Promise that resolves to the store address, as the node renders it.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const storeAddress = await supra.account.getPrimaryStoreAddress({ accountAddress: "0x1" });
      console.log(storeAddress);
      }

      runExample().catch(console.error);
    • Beta

      Queries the transaction history of an account: every finalized transaction that concerns the account, once each, with the categories it matched for the account. It lists the transfers of SUPRA held in primary fungible stores (the fa category), which getAccountCoinTransactions does not.

      Preview: wraps an API added in supra_node_v12.0.0, which may change until that release reaches Testnet.

      Type Parameters

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: {
                categories?: readonly AccountHistoryCategory[];
                count?: number;
                ascending?: boolean;
                start?: string;
            };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: {
              categories?: readonly AccountHistoryCategory[];
              count?: number;
              ascending?: boolean;
              start?: string;
          }
          • Optionalcategories?: readonly AccountHistoryCategory[]

            Return only transactions that matched at least one of these categories: "sent" (the account sent it), "coin" (coins moved in or out of the account), "fa" (a fungible asset store the account owned moved), "da" (a digital asset or object event names the account). Default: all four.

          • Optionalcount?: number

            The number of entries to scan for, 1 to 100 (default 20 on the node).

          • Optionalascending?: boolean

            Whether to return the entries in ascending order. Default descending.

          • Optionalstart?: string

            The cursor of the previous page, exclusive. Omit it, or pass undefined, for the first page.

      Returns Promise<AccountHistoryPage<T>>

      A Promise that resolves to the entries { categories, transaction } with an optional cursor, the indexedFrom height (x-supra-history-indexed-from) and the oldestBlock height (x-supra-oldest-block) when the node sends them; see AccountHistoryPage.

      • Needs a node from supra_node_v12.0.0 (Devnet). Mainnet and Testnet nodes at v11.7.x answer HTTP 404 for the route, which this method throws as SupraRouteUnsupportedError, a SupraNotFoundError.
      • Automated transactions and automation records are not listed; read them with Account.getAccountAutoTransactions.
      • The node applies categories while it scans the account's history, and reads at most 8 rows for each entry requested, so a page can hold fewer entries than count, or none, before the history is exhausted. The feed ends only when cursor is undefined, that is, when the response has no x-supra-cursor header. An empty page that has a cursor, and the cursor "0", do not end it.
      • A node that indexes blocks it held before it kept the history can lack the transactions of the blocks below indexedFrom.

      When the node is older than supra_node_v12.0.0.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.DEVNET });

      async function runExample() {
      const accountAddress = "0x1";
      let cursor: string | undefined;
      do {
      const page = await supra.account.getAccountHistory({
      accountAddress,
      options: { categories: ["sent", "fa"], count: 50, start: cursor },
      });
      for (const { categories, transaction } of page.response) {
      console.log(transaction.hash, categories);
      }
      cursor = page.cursor;
      } while (cursor !== undefined);
      }

      runExample().catch(console.error);
    • Queries the auto transactions of an account.

      Type Parameters

      Parameters

      • args: {
            accountAddress: AccountAddressInput;
            options?: {
                count?: number;
                block_height?: number;
                cursor?: string;
                ascending?: boolean;
            };
        }
        • accountAddress: AccountAddressInput

          The address of the account to query.

        • Optionaloptions?: { count?: number; block_height?: number; cursor?: string; ascending?: boolean }
          • Optionalcount?: number

            The number of transactions to return.

          • Optionalblock_height?: number

            Starting block height (inclusive). Optional. The block height at which to start lookup for transactions. If provided, returns options.count transactions starting from it in the order set by options.ascending.

          • Optionalcursor?: string

            The cursor of the previous page, exclusive. Omit it, or pass undefined, for the first page. If provided, returns options.count transactions after this cursor in the order set by options.ascending. If not specified, the lookup starts at options.block_height when it is given.

          • Optionalascending?: boolean

            Whether to return the transactions in ascending order.

      Returns Promise<PaginatedResponse<T[]>>

      A Promise that resolves to an array of AutoTransactionResponse objects representing the auto transactions of the account with optional cursor. cursor is undefined when there are no more transactions; see PaginatedResponse.

      • options.count defaults to 20 on the node; the SDK rejects a value outside 1 to 100.
      • options.block_height is ignored when options.cursor is given: if both are given, options.cursor has precedence.
      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const {response: accountAutoTransactions, cursor} = await supra.account.getAccountAutoTransactions({ accountAddress: accountAddress });
      console.log(accountAutoTransactions);
      }

      runExample().catch(console.error);
    • Queries the number of coin types an account holds: the legacy coins (CoinStore resources of the account) plus SUPRA when the account holds it as a fungible asset and has no CoinStore<SupraCoin> (an account that migrated its SUPRA with migrateCoinToFungibleStore has none), so SUPRA counts once. The node has no listing of an account's fungible asset stores, so fungible assets other than SUPRA are not counted.

      Parameters

      Returns Promise<number>

      A Promise that resolves to the number of legacy coins plus one when SUPRA is held as a fungible asset only.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountCoinsCount = await supra.account.getAccountCoinsCount({ accountAddress: accountAddress });
      console.log(accountCoinsCount);
      }

      runExample().catch(console.error);
    • Queries the total SUPRA balance of an account in quants: the CoinStore<SupraCoin> balance plus the balance of the account's SUPRA fungible asset store (0x1::coin::balance, which includes the paired fungible asset). The value is the SUPRA the account owns whichever form it is held in; getAccountSupraBalance reports the two forms separately. A fungible asset transfer (transferSupraFungibleAsset) moves only the fungible asset part.

      Parameters

      Returns Promise<bigint>

      A Promise that resolves to the total SUPRA balance of the account.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountSupraCoinBalance = await supra.account.getAccountSupraCoinBalance({ accountAddress: accountAddress });
      console.log(accountSupraCoinBalance);
      }

      runExample().catch(console.error);
    • Queries the SUPRA balance of an account in quants, in total and by the form in which it is held: as a legacy coin (CoinStore<SupraCoin>) and as a fungible asset (the primary store of the SUPRA fungible asset 0xa). total is 0x1::coin::balance, which already includes the fungible asset balance, so the two parts are not added twice. The two values are read by separate requests.

      Parameters

      Returns Promise<SupraBalance>

      A Promise that resolves to { total, coin, fungibleAsset }.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const { total, coin, fungibleAsset } = await supra.account.getAccountSupraBalance({ accountAddress: accountAddress });
      console.log(total, coin, fungibleAsset);
      }

      runExample().catch(console.error);
    • Queries the balance of a coin or fungible asset owned by an account. What the balance covers depends on asset:

      • A coin type (0x1::supra_coin::SupraCoin): 0x1::coin::balance, the CoinStore balance plus the balance of the paired fungible asset store.
      • A fungible asset address (0xa for SUPRA): 0x1::primary_fungible_store::balance, the account's primary store of that asset only. SUPRA held in a CoinStore is not included, so the balance of 0xa is 0 for an account that has not migrated its SUPRA.

      Parameters

      Returns Promise<bigint>

      A Promise that resolves to the balance of the coin or fungible asset owned by the account.

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const accountAddress = "0x1";
      const accountSupraCoinBalance = await supra.account.getAccountCoinBalance({ accountAddress: accountAddress, asset: "0x1::supra_coin::SupraCoin" });
      console.log(accountSupraCoinBalance);
      }

      runExample().catch(console.error);