Since the introduction of 0.3.x documentation I’ve had more chances to work with ComposeDB, so I thought to put together a list of some of the errors I’ve seen both myself, within the Discord and in the forums. This way, we can help future developers identify common pitfalls when working with ComposeDB and around some of the concepts I found particularly challenging when working with Ceramic Network.
First of all, please be aware that the following notes take into consideration documentation up to 0.3.x and have been created with the following packages in mind:
"@ceramicnetwork/blockchain-utils-linking": "^2.0.8",
"@ceramicnetwork/common": "^2.4.0",
"@ceramicnetwork/http-client": "^2.3.1",
"@composedb/client": "^0.3.0",
"@composedb/devtools": "^0.3.0",
"@composedb/devtools-node": "^0.3.0",
"@didtools/cacao": "^1.0.0",
"@didtools/pkh-ethereum": "^0.0.2",
It’s very likely these comments will be outdated in the incoming months.
General
-
What
node.jsversion should be used when running Ceramic packages? - I’ve run most packages successfully usingv16andv18, but anything below that will likely throw some errors. Make sure you are using any of the stable releases (i.e.,lts/gallium -> v16.19.0,lts/hydrogen -> v18.13.0) to avoid having silly errors that are hard to debug. -
Which package manager should I use when running Ceramic projects? - The recommended package is
pnpmsince most libraries are currently being developed withpnpm. Still, I struggled a bit when installing a few packages and ended up defaulting tonpm. Since a few Ceramic projects already have apackage-lock.jsonI avoidedyarnin most cases. -
Which packages should I still globally? - In general you will skip a few headaches if you at least install the cli globally (i.e.,
pnpm add -g @composedb/cli@^0.3.0, funny enough for global packagespnpmseems to be “better”). Remember that some commands that usenpxneed to have a reference to the package (e.g.,npx -p @ceramicnetwork/cli ceramic daemon). - What’s the easiest way to get started developing a Ceramic application? - The Ceramic team recently launched a Create Ceramic App template, which does an amazing job setting everything together for a Ceramic app using ComposeDB. To understand Ceramic DIDs, I recommend this video and for ComposeDB this video.
ComposeDB
-
How to start the daemon? - The recommended way is via the command
CERAMIC_ENABLE_EXPERIMENTAL_COMPOSE_DB='true' pnpm dlx @ceramicnetwork/cli daemon. Documentation for production deployments is still in progress. -
What’s this
DID_PRIVATE_KEYI need to setup? - It’s nothing more than a private key, but it’s used to generate an identity, particularly as an “Admin” for ComposeDB. You can usecomposedb did:generate-private-key, and remember that most references for this key are for the 32 bytes hexadecimal value and not itsdidrepresentation. Most setup errors come from missing this key. -
What’s the Admin DID for? - It’s the identity required on the “server” side of the
composeDBto setup a Composite for your node. You can write data into your Ceramic node with any DID, but the Admin DID is the only one able to modify schemas, composites et. al. -
What services and ports are important for ComposeDB? - A “successful” Ceramic daemon will kickstart the following process in the respective ports: Ceramic API in
7007, GraphQLi instance in5001, IPFSlib-p2pswarm port in4001. Other services might appear, and whenever these ports are busy they will iterate to the next second digit (e.g.5001to5011). - Why would I use ComposeDB? - Within the Ceramic Network, you can have DIDs write against streams, which are browsable by Id. You can’t easily fetch this information if you don’t know these Ids. ComposeDB allows you to compose and query data from various streams to easily showcase in your application without having to keep track of these yourself.
- I got some weird anchor commit error, what is that about? - Bear in mind right now, the Ceramic nodes use particular CAS nodes by the Ceramic team, which as with any infrastructure, if it is down or attacked, it might affect your developer experience.
DIDs
-
What is the most up-to-date way to write against a stream in Ceramic? - If you are new to Ceramic, I recommend straight away using only
did-session, as moving forward that seems to be the way to go. In the past, there have been other SDKs likeSelf.ID,Glazeand3Box-DID, so you might see these terms across the documentation. -
What’s
did-sessiongood for? - Unlike other DID providers previously mentioned,did-sessionprovides you with a text representation of your DID which you can use to create semi-permanent sessions for your users, as long as they are able to retrieve these from alocalStorageor similar. Be aware sessions do expire, throwing a few odd errors when they do. -
I want to control a DID with my Ethereum account, how can I do that? - The best place to start is here, and the package in question you’ll need is
@didtools/pkh-ethereumwhich is able to take an Ethereum provider. There are other providers, of course. - Can I create and control a DID w/o an Ethereum account and write against a Ceramic node? - Yes. Not all use cases of the Ceramic network rely on an blockchain account. For example, you could manage a DID from a server using a key provider.
-
What are great examples of usage of the Ceramic network that isn’t the Create Ceramic App? - My favorite is Sigle, which showcases the usage of
did-sessionwith Ethereum accounts quite well with React anduseContext.
Other
- Wen token? - There’s no communication about any token or any incentives from the Ceramic team. Right now most testnets are handled by the Ceramic network team, although there had been multiple exercises in the past to increase the number of Ceramic nodes by other parties.
-
What’s the history behind Ceramic - This doesn’t fit in a post, but you can google
uPortand3Boxto get an idea of some of the first projects around decentralized identifiers. - Does the Ceramic Network has anything to do with Ceramic tiles? - No.