@lichangio/lotus-client
v1.0.0
Published
Lotus JS Client
Downloads
3
Readme
Lotus JS Client
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:
- @filecoin-shipyard/lotus-client-schema (GitHub)
- @filecoin-shipyard/lotus-client-provider-browser (GitHub)
- @filecoin-shipyard/lotus-client-provider-nodejs (GitHub)
- @filecoin-shipyard/lotus-client-rpc (GitHub)
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>It will look like this: (5x speed)
From Node.js
https://github.com/alanshaw/js-lotus-client-examples
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").
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
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