by poetapp

poetapp / node

The core of

197 Stars 29 Forks Last release: 11 months ago (v2.24.0) MIT License 616 Commits 99 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

The Node

CircleCI Renovate enabled semantic-release Docker Automated build Join the chat at

The Node allows you to timestamp documents in a decentralized manner.

It's built on top of the Bitcoin blockchain and IPFS.


How to Run the Node

To run the Node, clone this repo, and make sure you have Docker and docker-compose installed.

Clone the repo:

git clone
cd node

To start the Node environment, run:

docker-compose up --build

Using the instructions above, new blocks have to be generated manually. This is often desirable during development. To have blocks automatically generated, follow the instructions below instead to mine a new block every 5 seconds.

  $ cp docker-compose.override.yml.example docker-compose.override.yml
  # Edit docker-compose.override.yml and uncomment
  # the `regtest-watcher` service in `docker-compose.yml`
  $ docker-compose up --build

You only need to run

docker-compose build
to create or update the Docker images, and
docker-compose up -d
to start them. To shut everything down, it is recommended to use
docker-compose down --volumes
to stop the running containers and clear any data. If you wish to keep data between invocations, use
docker-compose down

You can also

docker-compose exec mongo bash
docker-compose exec ipfs sh
to run the mongo shell or ssh into the IPFS container.


The Node depends on RabbitMQ, IPFS, Bitcoin Core and MongoDB.

These dependencies are setup automatically when you run



The Node comes with a default configuration that works out of the box, which can be found here:

By default, anchoring to the blockchain is disabled (

enableAnchoring: false
). If you want to enable blockchain anchoring, you will need to the Bitcoin Core dependency to be running with a funded wallet so that it can pay the Bitcoin network transaction fees (either for testnet or real Bitcoin for mainnet).

You can change any configuration by passing configuration values via environment variables. The keys of these environment variables are always the SCREAMINGSNAKECASE equivalent of the configuration options listed in the default configuration. For example, the RabbitMQ URL (

) can be set with the
environment variable.

Note: will NOT reload the configuration while it's running if you change it. You will need to restart the Node for configuration changes to apply.


Currently, the Node exposes four endpoints.

GET /works?issuer=xxx&limit=x&offset=x

Returns a paginated array of signed verifiable work claims.

Accepts the following query parameters:

  • issuer
    : string. If present, will only return works issued by this issuer.
  • limit
    : number. Maximum number of results to return per request. Defaults to 10.
  • offset
    : number. Number of claims to skip.

GET /works/:id

Returns a single signed verifiable work claim by its Id.

For simplicity, this endpoint adds a

in the response, which is not a real part of the claim, but provides valuable information such as the ID of the transaction in which this claim has been anchored, the IPFS directory hash in which it can be found, etc.

A 404 error is returned if the claim isn't found in this Node's database. This doesn't strictly mean the claim does not exist in the Network — it just doesn't exist in this Node.

POST /works

Publish a signed verifiable work claim.

This endpoint is async and returns an ACK, unless an immediate error can be detected (e.g., a malformed claim). There is no guarantee that the work has actually been processed, sent to IPFS and anchored. To confirm that, you'll need to

GET /works/:id
and check the

This endpoint expects a fully constructed signed verifiable claim — with the correct

, and
. See Building Claims for information on how to correctly create these attributes.

POST /files

Takes a multipart file upload. Currently only allows 1 file to be uploaded at a time and accepts 1 field which is the file to upload.

Returns an array with an object containing the hash and the archive URL of the file.


    hash: "QmS1s76raH43mLT3dSsMt7Nev1t9bM33GTFTZ9foXJV4ZT",
    archiveUrl: ""

Building Claims

A Claim is a signed verifiable claim that holds arbitrary information and allows the network to verify that the claim:

  • has actually been created by a specific person,
  • has not been modified since its creation, and
  • contains a special field
    which will allow more features in the future.

For more information about claims and their structure, please see:

Verifying the Claim is on Bitcoin's Blockchain

Once node receives a claim, it stores the claim with some metadata including the following: * The highest block read at the time node stores the claim * Placeholders for the actual block that was mined including the claim

This allows the node application to track whether or not the claim actually has been successfully saved to the Bitcoin blockchain. There is a configuration value,

, that determines how far ahead the blockchain will grow before resubmitting the claim. Comparing this value against the delta between the highest block read and the block read at the time of claim creation will determine whether node resubmits the claim. JS

All the claim logic is abstracted away in JS, so if you are working with JavaScript or TypeScript you can simply use the library:

import { configureCreateVerifiableClaim, createIssuerFromPrivateKey, getVerifiableClaimSigner } from ''

const { configureSignVerifiableClaim } = getVerifiableClaimSigner()

const issuerPrivateKey = 'LWgo1jraJrCB2QT64UVgRemepsNopBF3eJaYMPYVTxpEoFx7sSzCb1QysHeJkH2fnGFgHirgVR35Hz5A1PpXuH6' const issuer = createIssuerFromPrivateKey(issuerPrivateKey)

const createVerifiableWorkClaim = configureCreateVerifiableClaim({ issuer }) const signVerifiableClaim = configureSignVerifiableClaim({ privateKey: issuerPrivateKey })

const workClaim = { name: 'The Raven', author: 'Edgar Allan Poe', tags: 'poem', dateCreated: '', datePublished: '1845-01-29T03:00:00.000Z', archiveUrl: '', hash: '', }

const unsignedVerifiableClaim = await createVerifiableWorkClaim(workClaim) const signedWorkClaim = await signVerifiableClaim(unsignedVerifiableClaim)

You can find more examples on how to build and publish claims in the integration tests in tests/API/integration/PostWork.test.




npm run build
to compile the source. This will run TypeScript on the source files and place the output in
, and will then run Babel and place the output in

Currently, we're only using Babel to support absolute import paths.

During development, you can also run

npm run watch
to automatically watch for file changes, build the changed files and restart the application on the fly.


Unit and integration tests are located in this repo. You can run both with

npm test
or separately with
npm run test:unit
npm run test:integration

The integration tests run in isolated instances of the app and database.

Functional tests are run as follows:

  $ docker-compose build
  $ docker-compose up
  $ docker-compose exec poet-node npm run test:functional


Coverage is generated with Istanbul. A more complete report can be generated by running

npm run coverage
, which will run
npm run coverage:unit
npm run coverage:integration
together. You may also execute these commands separately.

Note: We are using our own forks of nyc and istanbul-lib-instrument in order to add better support for TypeScript. We intend to contribute our forks back to nyc and istanbul-lib-instrument in order to make our solution available to the entire community. You can follow the issues in this PR, and check the new PRs for istanbul-lib-instrument.


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.