Skip to content
No description, website, or topics provided.
Go Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/animagus Basic AST implementation for get balance example Dec 25, 2019
docs Basic AST implementation for get balance example Dec 25, 2019
examples Add streaming mode Jan 19, 2020
pkg Add streaming mode Jan 19, 2020
LICENSE Create LICENSE Dec 1, 2019
Makefile Add proto CI job Jan 16, 2020 Add introductory slide link Dec 26, 2019
go.mod Basic AST implementation for get balance example Dec 25, 2019
go.sum Basic AST implementation for get balance example Dec 25, 2019
tools.go Basic AST implementation for get balance example Dec 25, 2019


Note the code in this repository is still under development and NOT production ready. You should get familiar with CKB and know what you are doing before using it.

Animagus is a data processor for Nervos CKB. With a unified set of operations, it is designed to aid CKB in the following(but not limited to) tasks:

  • Indexing common cells
  • Aggregate balances
  • Signal special transactions, such as Nervos DAO deposits
  • Assemble transactions
  • Generate on-chain smart contracts

Animagus works by defining an AST(abstract syntax tree) first, the AST can be generated via any protobuf enabled languages. It's also possible to build small special purpose languages that compile directly to animagus' AST. Then with the AST, animagus can automatically scan CKB, index certain cells, and response to user request via grpc.

The name animagus comes from Harry Potter series. We are hoping with a well designed AST, animagus can help achieve most, if not all requirements needed when building wonderful dapps and a better ecosystem on CKB.

Note this project is still in fast development phase, the AST used is not yet in a stable state. We might modify it to add more capabilities.

We will continue to add docs here explaining how this project works once the AST is in a relatively more stable state, but if you want to get a taste right now, here's the slide for an introductory talk on animagus.

How to Run

We've packed a small example that can aggregate balances of different accounts in CKB. This can help overcome some of the challenges brought by CKB's unique flexibility.

Animagus requires the following dependencies:

Animagus is compatible with latest lina mainnet version of CKB. Below I'm building and launching CKB from source, but you can also use precompiled binaries:

$ mkdir -p /tmp/animagus-demo
$ cd /tmp/animagus-demo
$ git clone
$ cd ckb
$ cargo build --release
$ target/release/ckb init -C mainnet -c mainnet
$ target/release/ckb run -C mainnet

Now we can run the GraphQL server:

$ mkdir -p /tmp/animagus-demo
$ cd /tmp/animagus-demo
$ git clone
$ cd ckb-graphql-server
$ cargo build --release
$ target/release/ckb-graphql-server --db ../ckb/mainnet/data/db --listen

I'm using docker to quickly start that a temporary Redis server, but you can also using other ways to launch Redis:

$ docker run -d --rm -p 6379:6379 --name animagus-redis redis:alpine

First thing we need to do, is to generate an AST dump file for animagus, a sample has been prepared for this purpose:

$ mkdir -p /tmp/animagus-demo
$ cd /tmp/animagus-demo
$ git clone
$ cd animagus/examples/balance
$ go run generate_ast.go

You will noticed a new file balance.bin has been generated in animagus/examples/balance folder. Now we can start animagus:

$ cd /tmp/animagus-demo/animagus
$ make install-tools
$ go build ./cmd/animagus
$ ./animagus -astFile=./examples/balance/balance.bin

Notice if you use different ports for GraphQL server and Redis, you might need to tweak animagus start flags, see ./animagus --help for details

You will notice logs since animagus is indexing cells. We have prepared a small file that you can use to check balances. Given the args part in a lock script, this file queries against animagus for the current balance of that account:

$ cd /tmp/animagus-demo/animagus/examples/balance
$ ruby call_balance.rb ba03db27e31d19ebc4fda56b440fb92310d64d0e
You can’t perform that action at this time.