Skip to content

filecoin-shipyard/js-lotus-client

Repository files navigation

Lotus JS Client

Lotus Loves JS

The Lotus JS Client is a collection of small JavaScript libraries that you can use to control the Lotus implementation of Filecoin via its JSON-RPC API.

You can combine the libraries to build your own lightweight custom client that works in any JavaScript based environment!

Check out the full documentation, the official tutorial as well as the examples. Also check out the "Build" category in the Filecoin Docs for full tutorials and other ways to build things that use Filecoin.

Libraries

The following libraries are included:

Check the list of libraries page in the documentation for more information!

Usage

On the Web

Let's try using it with JavaScript in a web page!

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Chain Height</title>
  </head>
  <body>
    <h1>Chain Height</h1>
    <div id="chainHeight">Loading...</div>
    <script type="module">
      // Import ES modules from the npm packages via the unpkg.com CDN
      import { mainnet } from 'https://unpkg.com/@filecoin-shipyard/lotus-client-schema?module'
      import { BrowserProvider } from 'https://unpkg.com/@filecoin-shipyard/lotus-client-provider-browser?module'
      import { LotusRPC } from 'https://unpkg.com/@filecoin-shipyard/lotus-client-rpc?module'

      // Public endpoint for demos
      const endpointUrl = 'wss://lotus.testground.ipfs.team/api/0/node/rpc/v0'
      // To connect to your local Lotus node, try using:
      // const endpointUrl = 'ws://localhost:1234/rpc/v0'

      // Instantiate a provider for the endpoint -- wraps the http and
      // websockets transports for use in a web browser
      const provider = new BrowserProvider(endpointUrl)

      // Create a client object with callable methods using a schema and
      // our provider. Calling methods on this object will send JSON-RPC
      // requests over the websocket.
      const client = new LotusRPC(provider, { schema: mainnet.fullNode })

      // Using the client and the "ChainHead" method, every second,
      // retrieve the chain height and update the web page
      async function run () {
        const chainHeightEl = document.getElementById('chainHeight')
        while (true) {
          const { Height: height } = await client.chainHead()
          chainHeightEl.textContent = height
          await new Promise(resolve => { setTimeout(resolve, 1000) })
        }
      }
      run()
    </script>
  </body>
</html>

See it running here!

It will look like this: (5x speed)

Chain Head Demo

From Node.js

https://github.com/alanshaw/js-lotus-client-examples

(gist with quick example)

Full Tutorial

Check out the tutorial on docs.filecoin.io:

More examples

Here are some more examples to get started:

  • ObservableHQ Notebooks - Observable Notebooks are a great way to learn about and try out the API.
    • Here's the simplest example, which connects to the "local net" and gets the chain head
    • A more complex example connects to the Testnet and gets a list of miners and displays them on a 3D map using Deck.gl
    • And here's an example of how to query an ask from a miner on the Testnet
    • ... more to come. Submissions welcome!

We also built a workshop for the Ready Layer One conference. We have been updating it since the conference and it contains code that shows how to store and retrieve files using a Lotus node (connected to our demo "local net").

Workshop Videos

Documentation

Contributing

Feel free to join in. All welcome. Open an issue!

Conversations and questions about the Lotus JS Client libraries are welcome in the #fil-storage-dev channel in the Filecoin Commmunity Slack. Find out how to sign up over at the Filecoin Community page.

License

Dual-licensed under MIT + Apache 2.0

Releases

No releases published

Packages

No packages published