github.com/lmittmann/w3@v0.20.0/docs/pages/rpc-overview.mdx (about)

     1  # RPC Client
     2  
     3  <DocLink title="w3.Client" /> is a blazing fast RPC client, built on top of `go-ethereum/rpc.Client`. It is designed for **batch requests** and **easy extendibility**.
     4  
     5  ## Get Started
     6  
     7  <DocLink title="w3.Client" /> is a batch request focused RPC client that can be used to connect to an Ethereum node via HTTP, WebSocket, or IPC. Its modular API allows to create custom RPC method integrations that can be used alongside the common methods implemented by this package.
     8  
     9  <Steps>
    10  
    11  ### Connect to an RPC Endpoint
    12  
    13  Connect to an RPC endpoint via HTTP, WebSocket, or IPC using <DocLink title="w3.Dial" /> or <DocLink title="w3.MustDial" />.
    14  
    15  ```go
    16  client, err := w3.Dial("https://eth.llamarpc.com")
    17  if err != nil {
    18      // ...
    19  }
    20  defer client.Close()
    21  ```
    22  
    23  ### Make a Request
    24  
    25  Make a single HTTP request that calls two RPC methods.
    26  
    27  ```go
    28  var (
    29      balance *big.Int
    30      nonce   uint64
    31  )
    32  if err := client.Call(
    33      eth.Balance(addr, nil).Returns(&balance),
    34      eth.Nonce(addr, nil).Returns(&nonce),
    35  ); err != nil {
    36      // ...
    37  }
    38  ```
    39  
    40  </Steps>
    41  
    42  <Callout type="info">
    43  #### Why send batch requests?
    44  Most of the time you need to call multiple RPC methods to get the data you need. When you make separate requests per RPC call you need a single round trip to the server for each call. This can be slow, especially for remote endpoints. Batching multiple RPC calls into a single request only requires a single round trip, and speeds up RPC calls significantly.
    45  </Callout>
    46  
    47  ## Call
    48  
    49  <Callout type="info">Coming soon...</Callout>
    50  
    51  ## Call Contracts
    52  
    53  <Callout type="info">Coming soon...</Callout>
    54  
    55  ## Subscribe
    56  
    57  `w3.Client` supports subscriptions through the <DocLink title="Client.Subscribe" id="w3.Client.Subscribe" /> and <DocLink title="Client.SubscribeCtx" id="w3.Client.SubscribeCtx" /> methods. Subscriptions can be used to listen to events, emitted by the Ethereum node.
    58  
    59  ### Subscriptions
    60  
    61  * `eth.NewHeads(ch chan<- *types.Header)`: Subscribe to new block headers.
    62  * `eth.NewLogs(ch chan<- *types.Log, q ethereum.FilterQuery)`: Subscribe to new logs.
    63  * `eth.PendingTransactions(ch chan<- *types.Transaction)`: Subscribe to new pending transactions.
    64  
    65  #### Example: Subscribe to Pending Transactions
    66  
    67  Subscribe to new pending transactions ([Playground](https://pkg.go.dev/github.com/lmittmann/w3##example-Client-SubscribeToPendingTransactions)):
    68  
    69  ```go
    70  pendingTxCh := make(chan *types.Transaction)
    71  sub, err := client.Subscribe(eth.PendingTransactions(pendingTxCh))
    72  if err != nil {
    73      // ...
    74  }
    75  
    76  for {
    77      select {
    78      case tx := <-pendingTxCh:
    79          fmt.Printf("New pending tx: %s\n", tx.Hash())
    80      case err := <-sub.Err():
    81          fmt.Printf("Subscription error: %v\n", err)
    82          return
    83      }
    84  }
    85  ```
    86  
    87  ## Error Handling
    88  
    89  If one or more calls in a batch request fail, `Client.Call` returns an error of type <DocLink title="w3.CallErrors" />.
    90  
    91  #### Example: `w3.CallErrors`
    92  
    93  Check which RPC calls failed in a batch request ([Playground](https://pkg.go.dev/github.com/lmittmann/w3##example-Client-BatchHandleError))
    94  ```go
    95  var batchErr w3.CallErrors
    96  if err := client.Call(calls...); errors.As(err, &batchErr) {
    97      // handle call errors
    98  } else if err != nil {
    99      // handle other errors
   100  }
   101  ```