github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/docs/reference/tm2-js-client/Provider/provider.md (about)

     1  ---
     2  id: tm2-js-provider
     3  ---
     4  
     5  # Overview
     6  
     7  A `Provider` is an interface that abstracts the interaction with the Tendermint2 chain, making it easier for users to
     8  communicate with it. Rather than requiring users to understand which endpoints are exposed, what their return types are,
     9  and how they are parsed, the `Provider` abstraction handles all of this behind the scenes. It exposes useful API methods
    10  that users can use and expects concrete types in return.
    11  
    12  Currently, the `tm2-js-client` package provides support for two Provider implementations:
    13  
    14  - [JSON-RPC Provider](json-rpc-provider.md): executes each call as a separate HTTP RPC call.
    15  - [WS Provider](ws-provider.md): executes each call through an active WebSocket connection, which requires closing when
    16    not needed anymore.
    17  
    18  ## Account Methods
    19  
    20  ### getBalance
    21  
    22  Fetches the denomination balance of the account
    23  
    24  #### Parameters
    25  
    26  * `address` **string** the bech32 address of the account
    27  * `denomination` **string** the balance denomination (optional, default `ugnot`)
    28  * `height` **number** the height for querying.
    29    If omitted, the latest height is used (optional, default `0`)
    30  
    31  Returns **Promise<number\>**
    32  
    33  #### Usage
    34  
    35  ```ts
    36  await provider.getBalance('g1u7y667z64x2h7vc6fmpcprgey4ck233jaww9zq', 'atom');
    37  // 100
    38  ```
    39  
    40  ### getAccountSequence
    41  
    42  Fetches the account sequence
    43  
    44  #### Parameters
    45  
    46  * `address` **string** the bech32 address of the account
    47  * `height` **number** the height for querying.
    48    If omitted, the latest height is used. (optional, default `0`)
    49  
    50  Returns **Promise<number\>**
    51  
    52  #### Usage
    53  
    54  ```ts
    55  await provider.getAccountSequence('g1u7y667z64x2h7vc6fmpcprgey4ck233jaww9zq');
    56  // 42
    57  ```
    58  
    59  ### getAccountNumber
    60  
    61  Fetches the account number. Errors out if the account
    62  is not initialized
    63  
    64  #### Parameters
    65  
    66  * `address` **string** the bech32 address of the account
    67  * `height` **number** the height for querying.
    68    If omitted, the latest height is used (optional, default `0`)
    69  
    70  Returns **Promise<number\>**
    71  
    72  #### Usage
    73  
    74  ```ts
    75  await provider.getAccountNumber('g1u7y667z64x2h7vc6fmpcprgey4ck233jaww9zq');
    76  // 100
    77  ```
    78  
    79  ## Block methods
    80  
    81  ### getBlock
    82  
    83  Fetches the block at the specific height, if any
    84  
    85  #### Parameters
    86  
    87  * `height` **number** the height for querying
    88  
    89  Returns **Promise<BlockInfo\>**
    90  
    91  #### Usage
    92  
    93  ```ts
    94  await provider.getBlock(1);
    95  /*
    96  {
    97    block_meta: {
    98      block_id: {
    99        hash: "TxHKEGxFm/4+D7gxOJdVUaR+xTDZzlPrCVXuVm7SqHw=",
   100        parts: {
   101          total: "1",
   102          hash: "+dqI9oyngnnlKyno7y+RxCLEPA9FxWA/MmXyJ4uoJAY="
   103        }
   104      },
   105      header: {
   106        version: "v1.0.0-rc.0",
   107        chain_id: "dev",
   108        height: "1",
   109        time: "2023-05-01T10:32:20.807541Z",
   110        num_txs: "0",
   111        total_txs: "0",
   112        app_version: "",
   113        last_block_id: {
   114          hash: null,
   115          parts: {
   116            total: "0",
   117            hash: null
   118          }
   119        },
   120        last_commit_hash: null,
   121        data_hash: null,
   122        validators_hash: "FnuBaDvDLg4FotGRcZAFvhLkEjkb+kNLaAZrAVhL5Aw=",
   123        next_validators_hash: "FnuBaDvDLg4FotGRcZAFvhLkEjkb+kNLaAZrAVhL5Aw=",
   124        consensus_hash: "uKhnXFmGUkxgQSJf17ogbYLNXDo3UEPwQvzddo4Vkuw=",
   125        app_hash: null,
   126        last_results_hash: null,
   127        proposer_address: "g1vsqzyy9a4h9ah8cxzkaw09rpzy369mkl70lfdk"
   128      }
   129    },
   130    block: {
   131      header: {
   132        version: "v1.0.0-rc.0",
   133        chain_id: "dev",
   134        height: "1",
   135        time: "2023-05-01T10:32:20.807541Z",
   136        num_txs: "0",
   137        total_txs: "0",
   138        app_version: "",
   139        last_block_id: {
   140          hash: null,
   141          parts: {
   142            total: "0",
   143            hash: null
   144          }
   145        },
   146        last_commit_hash: null,
   147        data_hash: null,
   148        validators_hash: "FnuBaDvDLg4FotGRcZAFvhLkEjkb+kNLaAZrAVhL5Aw=",
   149        next_validators_hash: "FnuBaDvDLg4FotGRcZAFvhLkEjkb+kNLaAZrAVhL5Aw=",
   150        consensus_hash: "uKhnXFmGUkxgQSJf17ogbYLNXDo3UEPwQvzddo4Vkuw=",
   151        app_hash: null,
   152        last_results_hash: null,
   153        proposer_address: "g1vsqzyy9a4h9ah8cxzkaw09rpzy369mkl70lfdk"
   154      },
   155      data: {
   156        txs: null
   157      },
   158      last_commit: {
   159        block_id: {
   160          hash: null,
   161          parts: {
   162            total: "0",
   163            hash: null
   164          }
   165        },
   166        precommits: null
   167      }
   168    }
   169  }
   170  */
   171  ```
   172  
   173  ### getBlockResult
   174  
   175  Fetches the block at the specific height, if any
   176  
   177  #### Parameters
   178  
   179  * `height` **number** the height for querying
   180  
   181  Returns **Promise<BlockResult\>**
   182  
   183  #### Usage
   184  
   185  ```ts
   186  await provider.getBlockResult(1);
   187  /*
   188  {
   189    height: "1",
   190    results: {
   191      deliver_tx: null,
   192      end_block: {
   193        ResponseBase: {
   194          Error: null,
   195          Data: null,
   196          Events: null,
   197          Log: "",
   198          Info: ""
   199        },
   200        ValidatorUpdates: null,
   201        ConsensusParams: null,
   202        Events: null
   203      },
   204      begin_block: {
   205        ResponseBase: {
   206          Error: null,
   207          Data: null,
   208          Events: null,
   209          Log: "",
   210          Info: ""
   211        }
   212      }
   213    }
   214  }
   215  */
   216  ```
   217  
   218  ### getBlockNumber
   219  
   220  Fetches the latest block number from the chain
   221  
   222  Returns **Promise<number\>**
   223  
   224  #### Usage
   225  
   226  ```ts
   227  await provider.getBlockNumber();
   228  // 1300
   229  ```
   230  
   231  ## Network methods
   232  
   233  ### getNetwork
   234  
   235  Fetches the network information
   236  
   237  Returns **Promise<NetworkInfo\>**
   238  
   239  #### Usage
   240  
   241  ```ts
   242  await provider.getNetwork();
   243  /*
   244  {
   245    listening: true,
   246    listeners: [
   247      "Listener(@)"
   248    ],
   249    n_peers: "0",
   250    peers: []
   251  }
   252  */
   253  ```
   254  
   255  ### getConsensusParams
   256  
   257  Fetches the consensus params for the specific block height
   258  
   259  #### Parameters
   260  
   261  * `height` **number** the height for querying
   262  
   263  Returns **Promise<ConsensusParams\>**
   264  
   265  #### Usage
   266  
   267  ```ts
   268  await provider.getConsensusParams(1);
   269  /*
   270  {
   271    block_height: "1",
   272    consensus_params: {
   273      Block: {
   274        MaxTxBytes: "1000000",
   275        MaxDataBytes: "2000000",
   276        MaxBlockBytes: "0",
   277        MaxGas: "10000000",
   278        TimeIotaMS: "100"
   279      },
   280      Validator: {
   281        PubKeyTypeURLs: [
   282          "/tm.PubKeyEd25519"
   283        ]
   284      }
   285    }
   286  }
   287  */
   288  ```
   289  
   290  ### getStatus
   291  
   292  Fetches the current node status
   293  
   294  Returns **Promise<Status\>**
   295  
   296  #### Usage
   297  
   298  ```ts
   299  await provider.getStatus();
   300  /*
   301  {
   302    node_info: {
   303      version_set: [
   304        {
   305          Name: "abci",
   306          Version: "v1.0.0-rc.0",
   307          Optional: false
   308        },
   309        {
   310          Name: "app",
   311          Version: "",
   312          Optional: false
   313        },
   314        {
   315          Name: "bft",
   316          Version: "v1.0.0-rc.0",
   317          Optional: false
   318        },
   319        {
   320          Name: "blockchain",
   321          Version: "v1.0.0-rc.0",
   322          Optional: false
   323        },
   324        {
   325          Name: "p2p",
   326          Version: "v1.0.0-rc.0",
   327          Optional: false
   328        }
   329      ],
   330      net_address: "g1z0wa6rspsshkm2k7jlqvnjs8jdt4kvg4e9j640@0.0.0.0:26656",
   331      network: "dev",
   332      software: "",
   333      version: "v1.0.0-rc.0",
   334      channels: "QCAhIiMw",
   335      moniker: "voyager.lan",
   336      other: {
   337        tx_index: "off",
   338        rpc_address: "tcp://127.0.0.1:26657"
   339      }
   340    },
   341    sync_info: {
   342      latest_block_hash: "x5ewEBhf9+MGXbEFkUdOm3RsE40D+plUia2u0PuVfHs=",
   343      latest_app_hash: "7dB/+EmqLqEX2RkH2Zx+GcFo8c2vTs2ttW8urYyyFT4=",
   344      latest_block_height: "55",
   345      latest_block_time: "2023-05-06T11:28:35.643575Z",
   346      catching_up: false
   347    },
   348    validator_info: {
   349      address: "g1vsqzyy9a4h9ah8cxzkaw09rpzy369mkl70lfdk",
   350      pub_key: {
   351        "@type": "/tm.PubKeyEd25519",
   352        value: "X8ZS1DYu1eJ3HYnZ0OWk+0GgCdI7zA++kgWiprWMs3w="
   353      },
   354      voting_power: "0"
   355    }
   356  }
   357  */
   358  ```
   359  
   360  ### getGasPrice
   361  
   362  **NOTE: Not supported yet**
   363  
   364  Fetches the current (recommended) average gas price
   365  
   366  Returns **Promise<number\>**
   367  
   368  ### estimateGas
   369  
   370  **NOTE: Not supported yet**
   371  
   372  Estimates the gas limit for the transaction
   373  
   374  #### Parameters
   375  
   376  * `tx` **Tx** the transaction that needs estimating
   377  
   378  Returns **Promise<number\>**
   379  
   380  ## Transaction methods
   381  
   382  ### sendTransaction
   383  
   384  Sends the transaction to the node for committing and returns the transaction hash.
   385  The transaction needs to be signed beforehand.
   386  
   387  #### Parameters
   388  
   389  * `tx` **string** the base64-encoded signed transaction
   390  
   391  Returns **Promise<string\>**
   392  
   393  #### Usage
   394  
   395  ```ts
   396  await provider.sendTransaction('ZXhhbXBsZSBzaWduZWQgdHJhbnNhY3Rpb24');
   397  // "dHggaGFzaA=="
   398  ```
   399  
   400  ### waitForTransaction
   401  
   402  Waits for the transaction to be committed on the chain.
   403  NOTE: This method will not take in the fromHeight parameter once
   404  proper transaction indexing is added - the implementation should
   405  simply try to fetch the transaction first to see if it's included in a block
   406  before starting to wait for it; Until then, this method should be used
   407  in the sequence:
   408  get latest block -> send transaction -> waitForTransaction(block before send)
   409  
   410  #### Parameters
   411  
   412  * `hash` **string** The transaction hash
   413  * `fromHeight` **number** The block height used to begin the search (optional, default `latest`)
   414  * `timeout` **number** Optional wait timeout in MS (optional, default `15000`)
   415  
   416  Returns **Promise<Tx\>**
   417  
   418  #### Usage
   419  
   420  ```ts
   421  await provider.waitForTransaction('ZXhhbXBsZSBzaWduZWQgdHJhbnNhY3Rpb24');
   422  /*
   423  {
   424     messages:[], // should be filled with the appropriate message type
   425     fee:{
   426        gasWanted: "100",
   427        gasFee: "1ugnot"
   428     },
   429     signatures:[
   430        {
   431           pubKey:[
   432              {
   433                  type: "/tm.PubKeySecp256k1"
   434                  value: "X8ZS1DYu1eJ3HYnZ0OWk+0GgCdI7zA++kgWiprWMs3w="
   435              }
   436           ],
   437           signature: "X8ZS1DYu1eJ3HYnZ0OWk+0GgCdI7zA++kgWiprWMs3w="
   438        }
   439     ],
   440     memo: "check out gno.land!"
   441  }
   442  */
   443  ```