• Public
  • Public/Protected
  • All

Add support for new blockchain

Add support for new blockchain

This document contains a guide on how to add support for a new blockchain to the caip10-link doctype, as well as to use for authentication.

Overview: Ceramic and blockchain accounts

Ceramic interacts with blockchain accounts in two ways:

  • authentication
  • linking

Authentication. 3ID Connect (using 3id-did-provider) creates 3id (Ceramic flavour of DID) private keys based on an externally-provided entropy. It could be provided by a blockchain account by merely signing a well-known message. From a user's standpoint, it is authentication into Ceramic through her blockchain account, be it on Ethereum, Filecoin, EOS, Cosmos or something else. Same signature (=same entropy) generates same Ceramic DID.

Linking. In addition to generating a DID a user could also link additional blockchain accounts to a Ceramic DID. It establishes a relation blockchain account → DID that allows one to discover DID along with social profile based on just a blockchain account. Additionally, a link serves as a proof-of-ownership by DID over the blockchain account. This has proven to be useful for dApp personalization: one sees familiar names instead of 0xgibberish.

Below one additional process is mentioned: validation. It checks if proof-of-ownership in the link is formally correct, i.e., a well-known payload is really signed by the account that is declared in the link.

Adding a new blockchain

To add a new blockchain to Ceramic one has to implement both linking and validation.


We use CAIP-10 to represent accounts in a blockchain agnostic way. If the blockchain you want to add isn't already part of the CAIP standards you should make sure to add it there.

To add a new blockchain, one has to implement a new class implementing AuthProvider, put it into the @ceramicnetwork/blockchain-utils-linking package and export it. See existing auth providers for inspiration.

The auth provider is expected to be mainly called in a web browser as part of 3id-connect flow. The auth provider sits between 3id-connect (or 3ID DID Provider) and your blockchain account provider. In case of Ethereum, it might be MetaMask. The auth provider is responsible mainly for:

  • authentication (#authenticate): provide entropy
  • creating link (#createLink): create a LinkProof object which associates the specified AccountID with the DID

The auth provider is expected to know which blockchain account it currently serves. It reports it via #accountId. To reuse the same internal settings, e.g. a connection to a blockchain provider, but with a different account, the auth provider should have a #withAddress method.

To sum it all up, to add a new blockchain for linking:

  • add a new class implementing the AuthProvider interface to the @ceramicnetwork/blockchain-utils-linking package.
  • its authenticate method should ask the blockchain provider for an authentication signature and return 32 bytes in form of 0x-prefixed hex string.
  • its createLink method should ask the blockchain provider for a linking signature and return a LinkProof data structure.
  • its accountId method should return currently used account in the CAIP-10 format.
  • its withAccount method should return a new instance of the auth provider that serves a new account.


Validation is the counterpart of [#linking] that checks if the signature contained in a LinkProof corresponds to the declared account.

To add a new blockchain:

  • add a new file named after your blockchain to @ceramicnetwork/blockchain-utils-validation package
  • this file should expose an implementation of the BlockchainHandler interface, having:
    • CAIP-2 namespace for your blockchain
    • a validateLink function that checks if the linking signature was created by the account declared in the LinkProof argument
  • add the newly created BlockchainHandler to the handlers list in index.ts

Make sure that validateLink can validate links created by AuthProvider#createLink.

Supported blockchains

Below you can see a table which lists supported blockchains and their provider objects.

Blockchain CAIP-2 namespace Supported providers
Ethereum eip155 metamask-like ethereum provider
Filecoin fil Filecoin Wallet Provider
EOS eosio @smontero/eosio-local-provider