Grid Planaria is a programmable state machine which constructs itself by crawling the Bitcoin network.

Grid Planaria was designed as a replacement for Planaria Version 1. It is much more efficient, flexible, and powerful, and will eventually supersede Version 1.

Finally, Grid Planaria was built from scratch to be able to act as a host which powers many "Light Nodes", also known as Neon Planaria through Bitbus, forming a distributed global Bitcoin data grid.

Planaria Taxonomy

1. Planaria Types

There are three Planaria types:

  1. Planaria Version 1 (Full Node): The first version. Will be deprecated in the future and superseded by Grid Planaria.
  2. Grid Planaria (Full Node): Powered directly by Bitcoin. For heavy duty infra operators.
  3. Neon Planaria (Light Node): Powered by Bitbus, which synchronizes itself by crawling a Grid Planaria. Build state machines without running a full Bitcoin node. For app developers.

If you have been using the Planaria version 1, that's not going away, it will keep being maintained for bugfixes, etc. But do understand that Grid Planaria is the future, and all public Planaria nodes will also eventually migrate to Grid Planaria.

2. Which Planaria to Use

  • If you're interested in running a heavy duty Planaria node by directly crawling the Bitcoin network, Grid Planaria is for you.
  • If you're building a bitcoin application, you probably don't need to run a Grid Planaria.
    • If you want to build serverless apps, use public Planaria Endpoints. Bitcoin is not about running your own server, unless you really have to. The benefit of Bitcoin is that you can make money WITHOUT ever maintaining anything at all. For casual apps, this may be the way to go.
    • Often you may want to own your own data and serve your users from your own server. Or maybe you can't find a public Planaria node which provides the schema you want. In this case, you can build your own backend by synchronizing ONLY the subset of the blockchain you need for your app. See Neon Planaria:


Compared to the version 1, Grid Planaria is Minimal, Flexible, and Efficient.

1. Minimal

Grid Planaria does its job and gets out of the way. It's just a simple library, not a complex Docker container (Ironically, this makes it easier to containerize it in much more flexible ways).

Instead of acting as a one-stop shop that aims to take care of everything, Grid Planaria only does what it's good at:

  1. Event Emitter: Triggers onstartonblockonmempool events.
  2. Progress Tracker: Keeps track of state machine progress with an abstraction called "tape", which works the same way as Neon Planaria.
  3. Chain Management: Keeps its own cached blockchain which allows for asynchronous streaming based data processing, which keeps the memory usage low and makes everything efficient.

2. Flexible

No container restrictions. No DB restrictions. No API restrictions.


Unlike Planaria version 1 which came hardcoded with MongoDB, Grid Planaria doesn't make any assumptions about how developers use the framework. You can even run multiple databases.

By minimizing the API surface, it allows developers to integrate Planaria into their existing workflow or any other technology very easily. Also it's much easier to debug.

3. Efficient

Grid Planaria is powered by Bitwork, a simple and powerful Bitcoin networking library.

  • Significantly low memory usage. Maintains its own cache chain for efficiency. Uses streaming approach, which will be critical at scale.
  • Directly uses the P2P protocol to crawl from the Bitcoin network, which reduces memory usage significantly.
  • Also, all events are triggered directly from the P2P protocol instead of using ZeroMQ, which gets rid of occasional discrepancies and delays.