Skip to content

Instantly share code, notes, and snippets.

View jcnelson's full-sized avatar

Jude Nelson jcnelson

View GitHub Profile
jcnelson /
Last active September 18, 2023 15:59
Nakamoto WG

Last updated: 18 Sept 2023

This document describes the Nakamoto Workging Group for the Stacks Blockchain.


  • @jcnelson (lead)
  • @kantai
  • @jferrant
  • @xoloki
jcnelson /
Last active February 7, 2023 23:27

How to Participate in the Radon 2.1 Testnet

This gist describes how you can spin up a Stacks 2.1 node on the Bitcoin mainnet, and join a Radon testnet.

The Radon testnet behaves like the Stacks 2.1 mainnet will behave. It is based on the current 2.05 chain state, and is mined with real Bitcoin.

It is as close to a production environment as we can manage without hard-forking the mainnet chain.


jcnelson / toml
Last active November 22, 2022 17:35
Stacks 2.1 Testnet Configuration
working_dir = "$PATH_TO_YOUR_CHAINSTATE"
rpc_bind = ""
p2p_bind = ""
local_peer_seed = "$SOME_OTHER_PRIVATE_KEY"
prometheus_bind = ""
mine_microblocks = true
wait_time_for_microblocks = 0
bootstrap_node = ""
jcnelson /
Last active September 9, 2022 08:32
NFTrees: a Mineable, Stackable NFT


EDIT: So, I went ahead and built this out. Enjoy!

Instead of minting NFTs as they are purchased, an NFT project can instantiate them all on chain through a new NFT data structure called an NFTree. An NFTree is an authenticated filesystem of NFTs, composed of files (the NFTs themselves) organized into a hierarchy of directories. There is a root directory that contains all NFTs and other directories. Each directory contains the Merkle root of a Merkle tree constructed over its immediate children, thereby ensuring that each directory cryptographically represents its subtree in the filesystem.

Each file in the NFTree commits to the following metadata about the NFT:

  • Its cryptographic hash
  • Its size, in bytes
jcnelson /
Created November 16, 2021 13:50
How Stacking Helps the Network

PoX can't occur unless the network is sufficiently stable. The only way to get PoX to start for a reward cycle is to confirm a PoX anchor block with 80% confidence within a 100-block window called the "prepare phase." Miners collectively determine the anchor block when they mine blocks that descend from it -- if PoX begins, there will be exactly one Stacks block in which at least 80 of the 100 sortitions in the prepare phase are its descendants. By deciding on an anchor block, miners collectively determine what the PoX reward set will be. But in order to choose an anchor block, they have to have it in their chainstate; otherwise, they'd be unable to mine a block that descends from it. Miners don't know what the anchor block will be until the end of the prepare phase, so this means that they need all of the Stacks blocks in order to begin the next PoX reward cycle (since any Stacks block can be the anchor block -- even one from many reward cycles ago).

At the same time, because Stacks blocks are stored a

jcnelson /
Last active November 7, 2022 20:38

This is not to be confused with "subnets" that Hiro Systems is building. This is my own stab at building an off-chain causally-consistent asset trading system.

Disclaimer: I'm trying to flesh out a system that has only been described at a very high level. The purpose of this document is to write down notes on how I currently and tentatively believe subnets will work. This document is not authoritative, and may be significantly revised or even deleted.

All the credit for this approach goes to Aaron Blankstein. This document is based off of a conversation I had with him. I'm merely filling in the gaps.

What do we know about Subnets?

jcnelson /
Last active February 2, 2023 05:09


  • Oct 19 2021: deployed MVP v2 of the appchain mining contract and updated the links and examples in this document to use it instead.


Blockchains don't scale. The fact that all nodes process all transactions means that the blockchain only goes as fast as the slowest node allowed on the network. If that's something like a Raspberry Pi, then that's as fast as the blockchain goes.

And that's okay! The upside is that the more people can run nodes, the more resilient the blockchain will be. It's much harder to break a 10,000-node blockchain where most nodes run on home computers all across the world than a 10,000-node blockchain where most nodes run in a few datacenters.

jcnelson / appchain.clar
Last active October 17, 2021 12:23
;; Appchain MVP mining contract! Appchain peers scan the host chain (the chain that stores this contract and its state)
;; to discover one another and the appchain block metadata. From there, the appchain's miners proceed to work on their
;; chain by sending contract-call's to this contract to store more block metadata.
;; This contract essentially mimics the way Bitcoin behaves towards Stacks -- it's just a dumb data storage contract that
;; holds onto the same data that would go into Bitcoin transactions for mining. The only difference is that the appchain
;; uses STX as its underlying base currency for mining and PoX, instead of BTC.
(define-constant ERR_NO_RECIPIENTS u0)
(define-constant ERR_NO_COMMIT_SPEND u1)
jcnelson / gist:edc40f883b9105aac4e04420cc4d536a
Last active June 5, 2023 22:22
Blockchains Do Not Scale

Blockchains Do Not Scale

(Warning: rant)

Let me say that again for the people in the back. Blockchains. Do. Not. Scale. Period. Full Stop. Do not pass Go; do not collect $200. A scalable blockchain is a digital Philosopher's Stone -- a sought-after but non-existant substance surrounded by crazies, grifters, and the occult. If you gave these people money to buy their magic gold-transmuting eternal-live-producing crystalized spice melange, all you got was a rock.

The whole point of building anything at all on a blockchain is to make it so anyone who wants to can easily run a full replica of the code. This, and this alone, is what keeps blockchain networks both resilient and accountable to their users, since users by and large hold each other accountable. The easier it is to run a node, the more people will run nodes, and thus the more resilient the system will be to node failures, network partitions, and nefarious actors. The downside is that, because blockchains are a type of [replic

jcnelson / buff16-to-uint.clar
Last active April 8, 2022 10:23
(buff 16) to uint
;; lookup table for converting 1-byte buffers to uints via index-of
(define-constant BUFF_TO_BYTE (list
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
0x20 0x21 0x22 0x23 0x24 0x25 0x26 0x27 0x28 0x29 0x2a 0x2b 0x2c 0x2d 0x2e 0x2f
0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x3a 0x3b 0x3c 0x3d 0x3e 0x3f
0x40 0x41 0x42 0x43 0x44 0x45 0x46 0x47 0x48 0x49 0x4a 0x4b 0x4c 0x4d 0x4e 0x4f
0x50 0x51 0x52 0x53 0x54 0x55 0x56 0x57 0x58 0x59 0x5a 0x5b 0x5c 0x5d 0x5e 0x5f
0x60 0x61 0x62 0x63 0x64 0x65 0x66 0x67 0x68 0x69 0x6a 0x6b 0x6c 0x6d 0x6e 0x6f
0x70 0x71 0x72 0x73 0x74 0x75 0x76 0x77 0x78 0x79 0x7a 0x7b 0x7c 0x7d 0x7e 0x7f