@glif/filecoin-rpc-client
v3.0.2
Published
a convenience library for interacting with the Lotus jsonrpc
Downloads
5,733
Readme
Lotus JSON-RPC engine
A convenience library for interacting with the Lotus JSON-RPC api. We'll be actively updating and maintaining this library as needed for our use in the Filecoin web wallet. Several of the methods we're using are documented here.
Basic usage
npm i @glif/filecoin-rpc-client
const LotusRPCEngine = require('@glif/filecoin-rpc-client')
const lotusJWT = 'aaaaaaaa.bbbbbbbbbbbb.i_ZZZZZZ-3xYYYYYY'
const config = {
// defaults to local as seen below
apiAddress: 'http://127.0.0.1:1234/rpc/v0',
token: lotusJWT,
}
const lotusRPC = new LotusRpcEngine(config)
const chainHead = await lotusRPC.request('ChainHead')
Structuring requests
This library is simply a wrapper around Lotus' JSON-RPC. To send requests, follow this pattern:
lotusRPC.request(rpcmethod, arg1, arg2....etc) where the "methodName" corresponds to each available JSON-RPC method (found here). After the method name, each argument is passed to Lotus' JSON-RPC in the same order.
For example, the WalletBalance
JSON-RPC method takes a single argument, "address". Therefore, we should structure the request like:
const address = 't1jdlfl73voaiblrvn2yfivvn5ifucwwv5f26nfza'
const balance = await lotusRPC.request('WalletBalance', address)
Handling responses
When making a request to Lotus' JSON-RPC server, a success response looks like:
const successResponse = {
jsonrpc: '2.0',
result: 'fake response result',
id: 1,
}
The result
key is the return data as specified in the Lotus api. The Lotus JSON-RPC Engine will just return you the result
, and not any of the other data.
const errorResponse = {
jsonrpc: '2.0',
result: '',
id: 1,
error: {
code: 1,
message: 'Specific error returned by Lotus API',
},
}
This functionality may change, but for now, the Lotus JSON-RPC Engine will throw an error if the Lotus API comes back with an error, so be sure to catch them:
try {
// send a malformed request (need to pass an address)
await lotusRPC.request('WalletBalance')
} catch (err) {
console.log(err)
// 'get actor: GetActor called on undefined address' <== error directly passed from Lotus' API
}
Cids
Several JSON-RPC methods take Cid
as arguments. We need to structure a cid as:
const cid = {
'/': 'bafy2bzacedavr434vvbck3nkowrffk2x67lgl7kfujlw3lyj2zjvmihn5rf7i',
}
const message = await lotusRPC.request('ChainGetMessage', cid)
CORS
If you're planning on using this library in a web browser communicating with a raw Lotus node, you will run into CORS issues. There are a couple ways around this:
- Wrap your Lotus node in a proxy server that explicitly handles CORS requests. We're working on publishing a proxy server to help unstuck anyone who needs to take this route.
- Wrap your web browser in a "forwarder API", which is responsible for sending / receiving information from the Lotus node (essentially sending browser requests to a remote server to make the request to Lotus).
- Figure out how to handle CORS natively inside Lotus (not suggested). Security issues with this approach.
Contributing / development
If you're planning on forking this lib or developing with it locally, use the build script:
npm run build
Troubleshooting
Please make sure an existing issue doesn't already cover your problem before asking. If you don't see a similar issue, go ahead and file a new one in the repository.