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:

Filecoin Network Inspector Tutorial
Video: Build a chain explorer using Lotus - Vaibhav Saini, HackFS (2020.07.13)

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").

GitHub: filecoin-shipyard/js-lotus-client-workshop
Glitch: Try it here or remix it!

Workshop Videos

2020.07.13: Build a chain explorer using Lotus - Vaibhav Saini from HackFS
2020.05.31: 30 minute Workshop from Distributed Camp 2020
2020.05.08: 5 minute Lightning Talk Demo from IPFS Pinning Summit

Documentation

Lotus JS Client 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

filecoin-shipyard / js-lotus-client

readme