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.
Ceramic interacts with blockchain accounts in two ways:
Authentication. 3ID Connect (using
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
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.
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
@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:
#authenticate): provide entropy
#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
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
To sum it all up, to add a new blockchain for linking:
AuthProviderinterface to the
authenticatemethod should ask the blockchain provider for an authentication signature and return 32 bytes in form of
0x-prefixed hex string.
createLinkmethod should ask the blockchain provider for a linking signature and return a
accountIdmethod should return currently used account in the CAIP-10 format.
withAccountmethod 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:
namespacefor your blockchain
validateLinkfunction that checks if the linking signature was created by the account declared in the
handlerslist in index.ts
Make sure that
validateLink can validate links created by
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|