Built in 2021
filecoin-js-signer
Filecoin Signing Library
Filecoin signing library and RPC client in pure Typescript / Javascript with the necessary methods to interact with Filecoin, based on the existing WASM and Rust libraries.
Made with
In early 2021, building DeFi apps on Filecoin had a hard first step. Developers had to sign transactions and talk to built in actors like Payment Channels. Actors are Filecoin’s built in programs. The existing tools needed WASM bindings or Rust dependencies. That made them painful to use in React Native apps and in the browser.
The Filecoin Foundation gave a grant to Blits Labs to build decentralized loans with Atomic Swaps. Before that, we needed a signing library in pure JavaScript. No WASM. No native dependencies. Only TypeScript that runs anywhere.
I built filecoin-js-signer to fill that gap. It can create wallets, sign transactions, and work with Filecoin’s Payment Channel and Multisig actors.
A Signer and a Client
The library has two main parts: a Signer and a Client.
The Signer works offline. It generates mnemonics, the list of words that backs up a wallet. It derives keys from them with BIP-32 paths, a standard way to create many keys from one seed. It builds unsigned messages to send FIL, open payment channels, create vouchers and manage multisig wallets. It signs messages with secp256k1 and checks signatures.
The Client wraps the Signer and talks to the network. It connects to Filecoin nodes through JSON-RPC. It handles the nonce (the message counter for each account), gas estimation and broadcasting. You can create a payment channel, sign it and broadcast it in one call.
Payment channels were the main reason for the library. They let two people make many small payments off chain and settle once on chain. The library covers their full life:
- Create the channel.
- Issue vouchers, with an optional hash and secret pair.
- Redeem vouchers.
- Settle the channel.
- Collect the funds.
Vouchers with secrets were the missing piece for building Atomic Swaps.
Cryptography without WASM
The biggest challenge was avoiding WASM and native modules. I did every cryptographic operation with pure JavaScript libraries.
Key derivation uses BIP-32 with the Filecoin derivation path. The library makes a master key from a mnemonic, then derives a child key for each account. Each key pair has a secp256k1 private key, a public key and a Filecoin address.
To sign a message, the library first encodes it with CBOR. Then it computes a Blake2b-256 hash of those bytes and signs the hash with secp256k1. The signature format matches what Lotus, the main Filecoin node, expects: a 65 byte recoverable signature with the recovery byte at the end.
Address encoding was tricky. Filecoin uses its own format with a protocol indicator, a checksum and base32 encoding. I had to match the Rust implementation exactly so both would produce the same addresses.
Every byte must match
Filecoin encodes messages with CBOR (Concise Binary Object Representation), a compact binary format. The structure matters. Fields must come in the right order. Numbers must use the right encoding.
I used a forked version of the IPLD DAG-CBOR library. The fork handles BigNumbers correctly and produces output identical, byte for byte, to the Rust implementation. That was required for signature checks. A single different byte breaks everything.
Vouchers needed extra care. They hold nested structures with amounts, nonces, lanes and optional secrets. They also have a signature field that is filled in after signing. I wrote custom logic to handle both the signed and unsigned versions.
Talking to built in actors
Filecoin’s built in actors expect their parameters in a specific format. To create a payment channel, you encode the sender and recipient addresses. Then you wrap them with a CID that points to the actor’s code. A CID is a content identifier, a hash that names a piece of data.
The Init actor creates new actors. You send it an “Exec” message with the actor type and its constructor parameters. The new actor’s address comes back in the message receipt.
Multisig operations follow a similar pattern. A proposal encodes the destination address, the amount and the method. An approval points to the proposal by ID and includes a hash of the expected transaction. That stops front running attacks, where someone swaps in a different transaction before yours.
One flow for every call
The Client layer handles all network communication. It wraps a JSON-RPC client that connects to any Filecoin node (Lotus, Glif, etc.).
Every operation follows the same steps:
- Get the current nonce.
- Create the message.
- Estimate gas.
- Sign.
- Broadcast.
You can choose fire and forget mode, which returns a CID right away. Or you can choose wait mode, which blocks until the message is in a block.
Clear errors mattered. Network problems, insufficient funds, failed gas estimates and invalid signatures each need a clear message. The library throws typed exceptions, so callers can handle each case.
What the library taught me
Building filecoin-js-signer showed me what is hard about blockchain libraries.
Matching the network matters more than anything. A signing library must produce output that nodes accept. That means exact byte sequences, hash algorithms and encoding formats. I had to test a lot against the reference implementation.
Documentation brings users. I wrote an API reference with examples for every method. Developers copy and paste from docs, and good examples save them hours of debugging.
The library did its job. It let Blits Labs build Filecoin Loans. It removed the WASM barrier for JavaScript developers. It also proved that pure TypeScript can handle complex blockchain operations.
Interested in working together? Check out my services and pricing to see how we can collaborate on your next project. Let's Build