{"id":18325,"date":"2026-03-15T22:10:34","date_gmt":"2026-03-15T22:10:34","guid":{"rendered":"https:\/\/cryptoted.net\/index.php\/2026\/03\/15\/the-1-x-files-a-primer-for-the-witness-specification\/"},"modified":"2026-03-15T22:10:34","modified_gmt":"2026-03-15T22:10:34","slug":"the-1-x-files-a-primer-for-the-witness-specification","status":"publish","type":"post","link":"https:\/\/cryptoted.net\/index.php\/2026\/03\/15\/the-1-x-files-a-primer-for-the-witness-specification\/","title":{"rendered":"The 1.x Files: A Primer for the Witness Specification"},"content":{"rendered":"


\n<\/p>\n

\n

Since a lot of us have a bit more time on our hands, I thought now might be a good opportunity to proceed with something perhaps a little bit boring and tedious, but nevertheless quite fundamental to the Stateless Ethereum effort: understanding the formal Witness Specification.<\/p>\n

Like the captain of the Battleship in StarCraft, we’re going to take it slow. The witness spec is not a particularly complicated<\/strong> concept, but it is very deep<\/strong>. That depth is a little daunting, but is well worth exploring, because it’ll provide insights that, perhaps to your nerdy delight, extend well beyond the world of blockchains, or even software!<\/p>\n

By the end of this primer, you should have at least minimum-viable-confidence in your ability to understand what the formal Stateless Ethereum Witness Specification<\/a> is all about. I’ll try to make it a little more fun<\/em>, too.<\/p>\n

<\/g><\/svg><\/a>Recap: What you need to know about State<\/h2>\n

Stateless Ethereum is, of course, a bit of a misnomer, because the state is really what this whole effort is about. Specifically, finding a way to make keeping a copy of the whole Ethereum state an optional<\/strong> thing. If you haven’t been following this series, it might be worth having a look at my earlier primer<\/a> on the state of stateless Ethereum. I’ll give a short TL;DR here though. Feel free to skim if you feel like you’ve already got a good handle on this topic.<\/p>\n

\n

The complete \u2018state\u2019 of Ethereum describes the current status of all accounts and balances, as well as the collective memories of all smart contracts deployed and running in the EVM. Every finalized block in the chain has one and only one state, which is agreed upon by all participants in the network. That state is changed and updated with each new block that is added to the chain.<\/p>\n<\/blockquote>\n

The Ethereum State is represented in silico<\/em> as a Merkle-Patricia Trie<\/strong>: a hashed data structure that organizes each individual piece of information (e.g. an account balance) into one massive connected unit that can be verified for uniqueness. The complete state trie is too massive to visualize, but here’s a ‘toy version’ that will be helpful when we get to witnesses:<\/p>\n

\"toy<\/p>\n

Like magical cryptographic caterpillars, the accounts and code of smart contracts live in the leaves and branches of this tree, which through successive hashing eventually leads to a single root hash<\/strong>. If you want to know that two copies of a state trie are the same, you can simply compare the root hashes. Maintaining relatively secure and indisputable consensus over one ‘canonical’ state is the essence of what a blockchain is designed to do.<\/p>\n

In order to submit a transaction to be included in the next block, or to validate that a particular change is consistent with the last included block, Ethereum nodes must keep a complete copy of the state, and re-compute the root hash (over and over again). Stateless Ethereum is a set of changes that will remove this requirement, by adding what’s known as a ‘witness’.<\/p>\n

<\/g><\/svg><\/a>A Witness Sketch<\/h2>\n

Before we dive into the witness specification, it’ll be helpful to have an intuitive sense of what a witness is. Again, there is a more thorough explanation in the post on the Ethereum state linked above.<\/p>\n

A witness is a bit like a cheat sheet for an oblivious (stateless) student (client). It’s just the minimum amount of information need to pass the exam (submit a valid change of state for inclusion in the next block). Instead of reading the whole textbook (keeping a copy of the current state), the oblivious student (stateless client) asks a friend (full node) for a crib sheet to submit their answers.<\/p>\n

\n

In very abstract terms, a witness provides all of the needed hashes in a state trie, combined with some \u2018structural\u2019 information about where in the trie those hashes belong. This allows an \u2018oblivious\u2019 node to include new transaction in its state, and to compute a new root hash locally \u2013 without requiring them to download an entire copy of the state trie.<\/p>\n<\/blockquote>\n

Let’s move away from the cartoonish idea and towards a more concrete representation. Here is a “real” visualization of a witness:<\/p>\n

\"witness-hex\"<\/p>\n

I recommend opening this image in a new tab so that you can zoom in and really appreciate it. This witness was selected because it’s relatively small and easy to pick out features. Each little square in this image represents a single ‘nibble’, or half of a byte, and you can verify that yourself by counting the number of squares that you have to ‘pass through’, starting at the root and ending at an Ether balance (you should count 64). While we’re looking at this image, notice the huge chunk of code within one of the transactions that must be included for a contract call — code makes up a relatively large part of the witness, and could be reduced by code merkleization (which we’ll explore another day).<\/p>\n

<\/g><\/svg><\/a>Some Formalities<\/h2>\n

One of the fundamental distinguishing features of Ethereum as a protocol is its independence<\/em> from a particular implementation. This is why, rather than just one official<\/em> client as we see in Bitcoin, Ethereum has several completely different versions of client. These clients, written in various programming languages, must adhere to The Ethereum Yellow Paper<\/a>, which explains in much more formal terms how any<\/em> client should behave in order to participate in the Ethereum protocol. That way, a developer writing a client for Ethereum doesn’t have to deal with any ambiguity in the system.<\/p>\n

The Witness Specification has this exact goal: to provide an unambiguous<\/strong> description of what a witness is, which will make implementing it straightforward in any language, for all clients. If and when Stateless Ethereum becomes ‘a thing’, the witness specification can be inserted into the Yellow Paper as an appendix.<\/p>\n

When we say unambiguous<\/strong> in this context, it means something stronger than what you might mean in ordinary speech. It’s not that the formal specification is just a really, really, really, detailed description of what a witness is and how it behaves. It means that, ideally, there is literally one and only one way<\/strong> describe a particular witness. That is to say, if you adhere to the formal specification, it’d be impossible<\/strong> for you to write an implementation for Stateless Ethereum that generates witnesses different than any other implementation also following the rules. This is key, because the witness is going to (hopefully) become a new cornerstone of the Ethereum protocol; It needs to be correct by construction.<\/p>\n

<\/g><\/svg><\/a>A Matter of Semantics (and Syntax)<\/h2>\n

Although ‘blockchain development’ usually implies something new and exciting, it must be said that a lot of it is grounded in much older and wiser traditions of computer programming, cryptography, and formal logic. This really comes out in the Witness Specification! In order to understand how it works, we need to feel comfortable with some of the technical terms, and to do that we’re going to have to take a little detour into linguistics and formal language theory.<\/p>\n

Read aloud the following two sentences, and pay particular attention to your intonation and cadence:<\/p>\n