<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Udoka A.M. — Writing</title>
    <link>https://udokaam.dev/</link>
    <atom:link href="https://udokaam.dev/feed.xml" rel="self" type="application/rss+xml" />
    <description>Software engineering and developer relations. Build reports and long-form engineering writing.</description>
    <language>en</language>
    <lastBuildDate>Tue, 17 Nov 2026 00:00:00 GMT</lastBuildDate>
    <image>
      <url>https://udokaam.dev/favicon-512.png</url>
      <title>Udoka A.M. — Writing</title>
      <link>https://udokaam.dev/</link>
    </image>
    <item>
      <title>One viewing key, a million customers: account design, compact blocks and the real cost of finding incoming money</title>
      <link>https://udokaam.dev/writing/one-viewing-key-a-million-customers/</link>
      <guid isPermaLink="true">https://udokaam.dev/writing/one-viewing-key-a-million-customers/</guid>
      <pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Udoka A.M.</dc:creator>
      <category>zcash from the protocol up · lecture 2</category>
      <description>Lecture 2 of a ten-part engineering series. We price shielded payment discovery from the account model down to the decryption loop, with compact blocks and trial-decryption timings measured on Zcash mainnet and testnet.</description>
      <media:content url="https://udokaam.dev/writing/one-viewing-key-a-million-customers/cover.png" medium="image" />
      <content:encoded><![CDATA[<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/cover.png" alt="One viewing key, a million customers: what it costs a backend to find incoming money on Zcash" width="4000" height="1600" loading="lazy" decoding="async"></figure>
<p><strong>If a million customers each need a way to pay you on Zcash, how many keys should your backend watch, and what does each of those keys cost you every 25 seconds?</strong></p>
<p>That&#39;s today&#39;s question, and most engineers coming to Zcash answer it wrong the first time. The instinct from every other payments system is that cost follows addresses: a million customers means a million addresses means a million rows in an index, and an index lookup is cheap. On a shielded chain, that instinct points you at the wrong number. By the end of this lecture you will know which number to watch instead, you will have measured it on your own machine, and you will be able to size a scanner for a real workload before you write any of it.</p>
<p><strong>Welcome back to &quot;Zcash from the protocol up&quot;.</strong> In Lecture 1 we followed one payment through the stack in eight steps, and I said step 8, <em>discover</em>, is where most of a wallet backend&#39;s cost lives. Today we price step 8. The running example is still the shielded lane I built for Corridor Finance, which pays suppliers privately on Zcash testnet and lets an auditor check one customer&#39;s payments with a viewing key. The contrast case is still sealForge, my sealed-bid auction system, also on testnet. Today they turn out to sit at opposite ends of the same design decision, which is useful, because seeing both ends shows you it&#39;s a decision you get to make, with a price on each side.</p>
<p><strong>How this class works.</strong> Same as last time: history where it explains a design, then the mechanism, then something you run. Every number I give you today was either measured by me on 17 November 2026, with the command shown so you can repeat it, or comes from a ZIP or a source file I name. Where I&#39;m making a judgement rather than reporting a measurement, I&#39;ll say so.</p>
<h2 id="what-i-expect-you-to-know-already">What I expect you to know already</h2>
<p>You need Lecture 1, or the equivalent: what a shielded action is, that its 580-byte encrypted note holds the value and a 512-byte memo, and that an indexer serves compact blocks to wallets. Beyond that, the working knowledge of a backend engineer is enough.</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>You already know</th>
<th>Where we use it today</th>
</tr>
</thead>
<tbody><tr>
<td>Indexed lookups, and why a B-tree query is cheap</td>
<td>The transparent model, and why it stops working the moment the data is encrypted</td>
</tr>
<tr>
<td>Diffie-Hellman key agreement, at the &quot;two parties derive a shared secret&quot; level</td>
<td>Every trial decryption is one key agreement, and that is the expensive part</td>
</tr>
<tr>
<td>Stream ciphers and authenticated encryption</td>
<td>How a wallet reads 52 bytes of a note without the authentication tag</td>
</tr>
<tr>
<td>Protocol Buffers and gRPC streams</td>
<td>The CompactBlock message is a protobuf, streamed from the indexer</td>
</tr>
<tr>
<td>Capacity planning: throughput per worker, peak versus average, headroom</td>
<td>The whole second half of the lecture</td>
</tr>
<tr>
<td>Reading a little Rust and Python</td>
<td>Two short Rust programs and one Python planner in the lab</td>
</tr>
</tbody></table>
</div>
<p>You still don&#39;t need curve arithmetic. I&#39;ll tell you which operation is expensive and roughly why, and then we&#39;ll treat it as a measured constant, which is how you treat it in production anyway.</p>
<p><strong>What you will be able to do by the end.</strong> There are five outcomes, and we&#39;ll check them off at the end:</p>
<ol>
<li>Explain why detection cost on Zcash grows with the number of viewing keys you watch, and not with the number of addresses you hand out.</li>
<li>Derive a fresh address per customer or per invoice from one account, and map an incoming payment back to it.</li>
<li>Read a CompactBlock and say what it carries, what it leaves out, and what that costs you later.</li>
<li>Price a scanner in core-seconds per block from three numbers, and size it for the bursts the chain actually produces.</li>
<li>Choose an account granularity knowing what it fixes for you on day one: scan cost, disclosure, and what an auditor can be shown.</li>
</ol>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-01.png" alt="Fig 01. The ten-lecture map, with today's lecture highlighted" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 01. Lecture 2 is the first piece of the wallet backend core. Lectures 3 and 4 build on the scanner we size today: the indexer that feeds it, and the ledger that books what it finds.</em></p>
<h1>Part I: The account model</h1>
<h2 id="1-the-exchange-habit-one-transparent-address-per-customer">1. The exchange habit: one transparent address per customer</h2>
<p>Let&#39;s start with the design almost every exchange and payment processor reaches for first, because it works on Bitcoin and on Zcash&#39;s transparent pool, and because seeing exactly where it works tells you exactly where it stops.</p>
<p>You give each customer their own transparent address. When money arrives at that address, you know who sent it, because the address <em>is</em> the customer reference. Detection is a lookup: the node keeps an index from address to unspent outputs, and you ask it. In Zebra that is the <code>getaddressutxos</code> and <code>getaddresstxids</code> RPCs, and you can see the limits in Zebra&#39;s <code>zebra-rpc/src/methods.rs</code>: at most <strong>10,000 addresses per request</strong> (<code>MAX_REQUEST_ADDRESSES</code>), and at most <strong>100,000 results</strong> before the node rejects the query and asks you to narrow the height range (<code>MAX_ADDRESS_QUERY_RESULTS</code>).</p>
<p>Price that for a million customers and it is perfectly manageable. One poll is a hundred requests of ten thousand addresses each, the node does an index lookup per address, and the cost grows linearly with addresses at a small constant per address. Adding the millionth customer costs about what adding the first one did. This is the mental model most of us bring to Zcash, and on the transparent pool it&#39;s correct.</p>
<p>It also publishes everything. Every customer&#39;s balance, every payment, every amount and every time is readable by anyone with a block explorer, and because one address belongs to one customer, the chain hands a stranger a ready-made map of your customer book. For a payout system like Corridor&#39;s, that is the problem we came to Zcash to solve: suppliers don&#39;t want their competitors reading what they were paid. So the index-friendly design is ruled out for the money we care about, and the question becomes what replaces the index.</p>
<h2 id="2-why-shielded-detection-flips-the-cost-model">2. Why shielded detection flips the cost model</h2>
<p>The transparent design relies on one fact: the node can read the address on every output, so it can build an index keyed on it. A shielded output has no readable address. As we saw in Lecture 1, an action carries a note commitment, an ephemeral public key and a ciphertext, and nothing in those bytes says who it&#39;s for. The node cannot build an index of what it cannot read, and neither can the indexer.</p>
<p>So discovery works the other way round. The wallet takes every shielded output on the chain and asks, for each one, &quot;is this mine?&quot; The only way to answer is to try to decrypt it with your own key. That&#39;s <strong>trial decryption</strong>, and it&#39;s the single most important operation in this lecture.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-02.png" alt="Fig 02. One trial decryption: one incoming viewing key against one compact action" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 02. One trial, step by step. The key agreement in step 1 is a variable-base scalar multiplication on the Pallas curve, and it dominates the cost. Everything after it is cheap symmetric work. A miss and a hit cost almost the same, because you only learn which one it was at step 5.</em></p>
<p>Here is what happens in one trial, for the Orchard-protocol action format that both the Orchard and Ironwood pools use:</p>
<ol>
<li><strong>Key agreement.</strong> Multiply the action&#39;s ephemeral public key <code>epk</code> by your incoming viewing key <code>ivk</code>: <code>sharedSecret = [ivk] epk</code>. If the sender meant this note for you, this is the same secret the sender computed from your address, which is how two parties agree on a key without talking.</li>
<li><strong>Key derivation.</strong> Hash the shared secret and <code>epk</code> with BLAKE2b under the personalisation <code>Zcash_OrchardKDF</code> to get a symmetric key.</li>
<li><strong>Decrypt 52 bytes.</strong> Run the ChaCha20 keystream over the first 52 bytes of the ciphertext. Those bytes are the start of the note plaintext: a lead byte (1), the diversifier (11), the value (8) and <code>rseed</code> (32).</li>
<li><strong>Rebuild the commitment.</strong> You can&#39;t check the authentication tag, because it sits at the end of the full 580-byte ciphertext and we only have the first 52. So instead, recompute the note commitment from the plaintext you just decrypted.</li>
<li><strong>Compare.</strong> If your recomputed commitment equals the action&#39;s <code>cmx</code>, the note is yours and you now know its value. If not, it was garbage, and the note belongs to someone else.</li>
</ol>
<p>Steps 2 to 5 are microseconds of hashing and stream-cipher work. Step 1 is the cost. A scalar multiplication on an elliptic curve is the expensive primitive here, and you pay it once per <strong>(viewing key, action)</strong> pair, whether the trial hits or misses.</p>
<p>That gives us the cost model, and it is worth writing down as a formula because the rest of the lecture is this formula with numbers in it:</p>
<div class="code-block" data-lang="text"><div class="code-head"><span class="code-lang">Output</span></div><pre><code class="language-text">work per block  =  K  ×  I  ×  A  ×  t

K  viewing-key accounts you watch
I  incoming viewing keys per account (2: external and internal, see below)
A  shielded actions and outputs in the block
t  time for one trial on one core</code></pre></div>
<p>Notice there&#39;s no term for addresses in that formula, and that&#39;s the whole flip: on the transparent pool, cost grows with the number of addresses you index. On the shielded pools, cost grows with the number of keys you hold, times the size of the chain, and it doesn&#39;t care how many addresses each key has handed out.</p>
<p>The <code>I = 2</code> comes from how wallets use keys. Each account has an <em>external</em> incoming viewing key, for addresses you give to other people, and an <em>internal</em> one, for change sent back to yourself. A wallet has to try both, and librustzcash&#39;s scanner does exactly that: look for the <code>for scope in [Scope::External, Scope::Internal]</code> loops in <code>zcash_client_backend/src/scanning.rs</code>. If you only ever receive and never send from an account, you could skip the internal key, but most backends send, so count two.</p>
<h2 id="3-diversified-addresses-one-key-288-addresses">3. Diversified addresses: one key, 2^88 addresses</h2>
<p>If cost follows keys and not addresses, the obvious move is to hand out as many addresses as you like from as few keys as you can. Zcash was designed for exactly that, and the feature has a name: <strong>diversified addresses</strong>.</p>
<p>An Orchard-protocol address is a pair <code>(d, pk_d)</code>. The diversifier <code>d</code> is 11 bytes. The transmission key is <code>pk_d = [ivk] g_d</code>, where <code>g_d</code> is a curve point derived by hashing <code>d</code>. Look at what that means: the same <code>ivk</code> sits inside every address, so the same <code>ivk</code> opens notes sent to any of them. One key, one trial per action, however many addresses you&#39;ve issued.</p>
<p>Where does <code>d</code> come from? ZIP 32 gives each account a 32-byte diversifier key <code>dk</code>, and the diversifier for index <code>j</code> is <code>d = FF1-AES256(dk, j)</code>, a format-preserving encryption of the 88-bit index. Two consequences matter to us:</p>
<ul>
<li><strong>The addresses are unlinkable.</strong> Without the viewing key, two diversified addresses from the same account look like addresses from two different wallets, because each <code>d</code> is an encryption and each <code>pk_d</code> depends on it. So a fresh address per customer doesn&#39;t leak that those customers pay the same business.</li>
<li><strong>The mapping runs backwards for free.</strong> Because FF1 is a block cipher, the holder of <code>dk</code> can decrypt a diversifier back into its index. When a trial decryption hits, the plaintext includes <code>d</code>, so you recover <code>j</code>, and if <code>j</code> is your invoice number, you know which invoice was paid. Nothing to store.</li>
</ul>
<p>For the Orchard protocol every one of the 2^88 indices gives a valid address. (Sapling also has diversified addresses, but roughly half of its diversifiers are invalid and get skipped, a small wrinkle you&#39;ll meet if you support Sapling receivers.) In practice you wrap the address in a Unified Address, per ZIP 316, which is the string a customer actually sees. sealForge scans both the Orchard and Ironwood pools with one Orchard-protocol incoming viewing key; open <code>crates/sealforge-scan/src/lib.rs</code> and you&#39;ll see <code>scan_compact_block</code> try the same <code>ivk</code> against <code>tx.actions</code> and <code>tx.ironwood_actions</code>.</p>
<p>So a merchant checkout that issues a million invoices from one account pays for one key. The scan cost of the millionth invoice is zero, and the cost of deriving its address is one scalar multiplication and one FF1 call, about 113 µs on my laptop (we&#39;ll measure it in the lab).</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-03.png" alt="Fig 03. Three ways to give a million customers somewhere to pay you" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 03. Three account models side by side. The transparent model is cheap to detect and public. One account per customer is private but multiplies the scan by a million. One account with a diversified address per customer is private and costs one key. The question is what the third model gives up, and that&#39;s section 4.</em></p>
<h2 id="4-the-catch-a-viewing-key-discloses-the-whole-account">4. The catch: a viewing key discloses the whole account</h2>
<p>If diversified addresses were free in every sense, you&#39;d always use one account and we&#39;d be done. They&#39;re not, and the reason is the same property that makes them cheap: one key opens all of them.</p>
<p>A viewing key is a disclosure tool as well as a detection tool. Give someone your account&#39;s incoming viewing key and they can see every payment to every address that account ever issued. There is no way to cut a viewing key down to one diversified address, because the address <em>is</em> the key with a different <code>d</code>. So the account boundary is also the disclosure boundary. Whoever you&#39;ll ever need to show something to, they see the whole account or nothing.</p>
<p>And the boundary is fixed at creation. You can&#39;t split an account later without moving its funds into new accounts, which is a set of transactions with fees and a visible pattern. So the account model is one of the few decisions in this series that you genuinely can&#39;t refactor cheaply, and it should be made with three things on the table at once: scan cost, who needs to see what, and for how long.</p>
<p>Here&#39;s how the two reference projects and the makeshift one land on that decision:</p>
<ul>
<li><strong>Corridor&#39;s shielded lane: one vault per (customer, period).</strong> Corridor&#39;s auditor needs to check one customer&#39;s payouts for one period, and nothing else. So each (customer, period) pair gets its own shielded vault, either a ZIP 32 account or a FROST 2-of-3 vault, and the auditor gets that one vault&#39;s viewing key and reruns the same scan Corridor&#39;s ledger reconciles against. That&#39;s the expensive end of the trade-off: every vault is a key the scanner watches, so 500 vaults is <code>K = 500</code>. I chose it deliberately, because the disclosure requirement is the product.</li>
<li><strong>sealForge: one escrow per auction, viewing key published.</strong> sealForge discloses an escrow to <em>everyone</em>: after an auction closes, the escrow&#39;s incoming viewing key is published so anyone can recompute the result. A fresh escrow per auction is what makes that safe, since publishing the key reveals that auction&#39;s bids and nothing from any other auction. Same tool as Corridor, opposite audience.</li>
<li><strong>The makeshift checkout service: one account, a diversified address per invoice.</strong> A merchant that never has to disclose one customer&#39;s payments separately can collapse everything into one account and issue an address per invoice. That&#39;s <code>K = 1</code> for any number of customers, and the price is that the only disclosure unit is &quot;everything&quot;.</li>
</ul>
<p>The pattern underneath is the lesson of this section: <strong>account granularity, disclosure granularity and scan cost are the same decision.</strong> If you need to show an auditor one customer, that customer needs their own key, and you pay for that key on every block forever.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-04.png" alt="Fig 04. Account granularity is disclosure granularity is scan cost" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 04. The three reference designs placed on the trade-off. Moving left buys finer disclosure and costs keys. Corridor sits left because its auditor must see one customer and one period; the checkout service sits right because nobody needs anything finer than &quot;the whole merchant&quot;.</em></p>
<h1>Part II: Compact blocks and the work per block</h1>
<h2 id="5-what-a-compactblock-carries-and-what-it-leaves-out">5. What a CompactBlock carries, and what it leaves out</h2>
<p>Now that we know the scanner&#39;s job is &quot;try every key against every action&quot;, let&#39;s look at what it&#39;s actually fed. The indexer turns each full block into a <strong>CompactBlock</strong>, defined in <code>compact_formats.proto</code> in the lightwallet-protocol repository, and streams them over gRPC with <code>GetBlockRange</code>. I read the definitions below from the generated Rust in <code>zcash_client_backend 0.25.0-pre.2</code>.</p>
<p>A <code>CompactBlock</code> has the block&#39;s <code>height</code>, <code>hash</code>, <code>prevHash</code> and <code>time</code>, an empty <code>header</code> field reserved for later, a list of <code>CompactTx</code>, and a <code>ChainMetadata</code> with the size of the Sapling, Orchard and Ironwood note commitment trees at the end of the block. Each <code>CompactTx</code> has its index in the block, its <code>txid</code>, a <code>fee</code> when the server can compute it, and then one list per pool:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Bytes per entry</th>
<th>What it&#39;s for</th>
</tr>
</thead>
<tbody><tr>
<td><code>spends</code></td>
<td><code>CompactSaplingSpend</code></td>
<td>32 (nullifier)</td>
<td>Detecting your own Sapling spends</td>
</tr>
<tr>
<td><code>outputs</code></td>
<td><code>CompactSaplingOutput</code></td>
<td>116 (<code>cmu</code> 32, <code>ephemeralKey</code> 32, ciphertext 52)</td>
<td>Trial-decrypting Sapling outputs</td>
</tr>
<tr>
<td><code>actions</code></td>
<td><code>CompactOrchardAction</code></td>
<td>148 (<code>nullifier</code> 32, <code>cmx</code> 32, <code>ephemeralKey</code> 32, ciphertext 52)</td>
<td>Orchard</td>
</tr>
<tr>
<td><code>ironwood_actions</code></td>
<td><code>CompactOrchardAction</code></td>
<td>148</td>
<td>Ironwood, the same message type as Orchard</td>
</tr>
<tr>
<td><code>vin</code>, <code>vout</code></td>
<td><code>CompactTxIn</code>, <code>TxOut</code></td>
<td>prevout, or value plus script</td>
<td>Transparent data, only if you ask for it</td>
</tr>
</tbody></table>
</div>
<p>Two things stand out. First, a compact action is 148 bytes against the full action&#39;s 820, so about 18%: the scanner gets the ephemeral key it needs for step 1 of Fig 02, the 52 bytes it needs for step 3 and the <code>cmx</code> it needs for step 5, and nothing else. The other 672 bytes, which include the rest of the ciphertext with the memo and the 80-byte <code>outCiphertext</code>, stay on the server. Second, transparent data is opt-in: the <code>BlockRange</code> request has a <code>pool_types</code> field, and if you leave it empty the server returns shielded data only. So if you measure this yourself and see <code>vin=0 vout=0</code> across five thousand blocks like I did, nothing is broken, that&#39;s just the default at work.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-05.png" alt="Fig 05. A full action against a compact action, and a CompactBlock's layout" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 05. The scanner gets 148 of each action&#39;s 820 bytes. The memo is in the 528 bytes of ciphertext it doesn&#39;t get, which is why every hit costs a second fetch (section 8).</em></p>
<p>The design goal for compact blocks is spelled out in the proto comment: carry only what a wallet needs to detect payments to it, detect spends of its notes, update the witnesses it needs to spend, and spend transparent outputs it owns. Detection, which is our subject, needs the 148 bytes. Spend detection needs only the nullifiers, and that&#39;s a set lookup against the nullifiers of notes you already hold, so it&#39;s cheap and I&#39;ll leave it aside. Witness maintenance used to mean hashing every note commitment on the chain into your tree; current librustzcash wallets avoid most of that with the <code>GetSubtreeRoots</code> RPC and the <code>suggest_scan_ranges</code> logic in <code>zcash_client_backend::data_api::chain</code>, which together let a wallet scan the ranges that matter first and fill in the tree around its own notes.</p>
<h2 id="6-measured-what-the-chain-actually-carries">6. Measured: what the chain actually carries</h2>
<p>Formulas are only as good as the <code>A</code> you put in them, so let&#39;s measure <code>A</code>. I streamed the latest 5,000 compact blocks from public servers on 17 November 2026 with the first lab program, once on mainnet and once on testnet:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th></th>
<th>Mainnet (<code>zec.rocks</code>)</th>
<th>Testnet (<code>testnet.zec.rocks</code>)</th>
</tr>
</thead>
<tbody><tr>
<td>Heights</td>
<td>3,577,678 – 3,582,677</td>
<td>4,626,363 – 4,631,362</td>
</tr>
<tr>
<td>Compact bytes per block, average</td>
<td>2,083</td>
<td>1,621</td>
</tr>
<tr>
<td>Ironwood actions</td>
<td>60,551</td>
<td>46,387</td>
</tr>
<tr>
<td>Orchard actions</td>
<td>309</td>
<td>38</td>
</tr>
<tr>
<td>Sapling outputs / spends</td>
<td>681 / 360</td>
<td>2 / 0</td>
</tr>
<tr>
<td>Shielded outputs per block, average</td>
<td>12.3</td>
<td>9.3</td>
</tr>
<tr>
<td>Most shielded outputs in one block</td>
<td>311</td>
<td>315</td>
</tr>
</tbody></table>
</div>
<p>Ironwood carries almost everything, which is what you&#39;d expect after the Orchard seal: Orchard actions only appear when funds leave the old pool, and Sapling is a trickle. Five thousand blocks is about 35 hours at 25-second spacing, and at 2 kB per block a wallet following the chain downloads roughly 7 MB of compact blocks a day on mainnet right now.</p>
<p>The average is the wrong number to plan with, though, and the mainnet data shows why better than I could have staged it.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-06.png" alt="Fig 06. Shielded outputs per block across 5,000 mainnet blocks" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 06. 62% of blocks carry no shielded output at all, and the median is zero. Then, over about three hours, 153 blocks arrive with more than 250 outputs each, many of them back to back. Those 153 blocks hold 75% of all the shielded outputs in the sample.</em></p>
<p>Look at the distribution: 3,104 of the 5,000 blocks (62%) had no shielded outputs, another 1,565 had between one and ten, and then there&#39;s a cluster of 153 blocks between heights 3,579,935 and 3,580,346, about three hours of chain, with more than 250 outputs each, often in consecutive blocks. The 99th percentile block has 303 outputs. I don&#39;t know who sent that burst, and for capacity planning it doesn&#39;t matter: someone can fill blocks, and your scanner has to keep up when they do.</p>
<p>There&#39;s a hard ceiling, and it&#39;s new. ZIP 218, the same proposal that brought 25-second blocks in NU7, also introduced per-block action limits: a global shielded budget of <strong>330 actions per block</strong> across all pools, at most 330 Orchard and at most 330 Ironwood actions, and at most 300 Sapling spends plus outputs. The ZIP&#39;s own rationale is partly about wallets: it calculates that under these limits the worst-case light-client load is 169 MB of bandwidth and <strong>2.3 million trial decryptions per day</strong>, down 37% in bandwidth from the old worst case despite three times as many blocks. That 2.3 million is 330 actions × 3,456 blocks a day × 2 keys per account, so the ZIP is doing the same arithmetic we are, for one account.</p>
<p>So we have three values of <code>A</code> to plan with: about 12 on an average block, about 300 at the 99th percentile, and 330 as the consensus cap. Plan for the cap. It&#39;s only 9% above the 99th percentile, and it&#39;s a bound the chain guarantees, which is more than you can say for any percentile.</p>
<h2 id="7-pricing-the-work-per-block">7. Pricing the work per block</h2>
<p>Now <code>t</code>, the time for one trial. I timed <code>try_compact_note_decryption</code> from <code>zcash_note_encryption 0.5.1</code> against real Ironwood actions from testnet (all 46,387 from the 5,000-block sample for one key, and a 932-action sample from a 1,000-block run for 10 and 100 keys), with randomly generated incoming viewing keys, on one core of an Apple M3 Pro, release build:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Keys</th>
<th>Trials</th>
<th>One at a time</th>
<th>Batch API</th>
</tr>
</thead>
<tbody><tr>
<td>1</td>
<td>46,387</td>
<td>83 µs per trial</td>
<td>51 µs per trial</td>
</tr>
<tr>
<td>10</td>
<td>9,320 (932 actions)</td>
<td>81 µs</td>
<td>42 µs</td>
</tr>
<tr>
<td>100</td>
<td>93,200 (932 actions)</td>
<td>82 µs</td>
<td>42 µs</td>
</tr>
</tbody></table>
</div>
<p>Every trial missed, which is the realistic case: nearly every action on the chain belongs to someone else, and a miss costs the same as a hit. The batch API, <code>zcash_note_encryption::batch::try_compact_note_decryption</code>, takes a slice of keys and a slice of outputs and amortises the per-output preparation across the batch, which roughly halves the cost here. librustzcash&#39;s own scanner batches for the same reason, through <code>BatchRunner</code>. I&#39;ll use <strong>t = 42 µs per trial per core</strong> from here on. Your number will differ, which is why the lab has you measure it.</p>
<p>Put the pieces together, <code>K × 2 × A × 42 µs</code>, and divide by the 25 seconds you have before the next block arrives:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Accounts watched (K)</th>
<th>Average block (A = 12.3)</th>
<th>Full block (A = 330)</th>
<th>Cores to keep up with full blocks</th>
</tr>
</thead>
<tbody><tr>
<td>1</td>
<td>1 ms</td>
<td>28 ms</td>
<td>0.001</td>
</tr>
<tr>
<td>500 (Corridor&#39;s design target)</td>
<td>0.5 s</td>
<td>13.9 s</td>
<td>0.55</td>
</tr>
<tr>
<td>10,000</td>
<td>10 s</td>
<td>277 s</td>
<td>11</td>
</tr>
<tr>
<td>1,000,000 (an account per customer)</td>
<td>17 min</td>
<td>7.7 hours</td>
<td>1,109</td>
</tr>
</tbody></table>
</div>
<p>That last row is the one I want you to remember. An account per customer, for a million customers, needs about a thousand cores <em>just to keep up with full blocks</em>, before you&#39;ve done anything with what you found. The same million customers as diversified addresses on one account need 28 milliseconds of one core per full block. Same customers, same privacy from the outside world, a difference of six orders of magnitude, and the only thing that changed was where the account boundary sits.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-07.png" alt="Fig 07. Cores needed to keep up, by number of accounts watched" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 07. Scan cost is linear in accounts, so on log axes it&#39;s a straight line, one for average blocks and one for full ones. The diversified-address design is a flat line at K = 1, however many customers it serves. The gap between average and full is the burst you saw in Fig 06, and it&#39;s 27×.</em></p>
<p>Catch-up is the other bill. A new auditor, a restored backup or a new worker has to scan history, and history is paid at the average rate rather than the cap, because it&#39;s already happened. One day of mainnet history is 3,456 blocks; for Corridor&#39;s 500 vaults that&#39;s about 30 core-minutes per day of history at today&#39;s volume, so a year of history is about 180 core-hours. That parallelises cleanly across height ranges, which is how you should shard a rescan, and it&#39;s also why the account decision is irreversible in practice: every key you add, you also pay to scan backwards to its birthday.</p>
<h2 id="8-the-second-fetch-memos-cost-a-round-trip-each">8. The second fetch: memos cost a round trip each</h2>
<p>The scanner now knows <em>that</em> a payment arrived and its value, from the 52 decrypted bytes. It doesn&#39;t know <em>what it&#39;s for</em>. The memo, the 512 bytes where Corridor puts its <code>INV-… / corridor:&lt;ref&gt;</code> invoice reference and sealForge puts its bid commitment, is in the part of the ciphertext the compact block left on the server.</p>
<p>So every hit costs a second fetch: <code>GetTransaction</code> with the txid, then full decryption with <code>try_note_decryption</code>, which this time checks the authentication tag and returns the memo. sealForge&#39;s scanner is written as exactly these two phases, and you can lift the pattern directly: <code>scan_compact_block</code> returns the txids that pay the escrow, and <code>decrypt_transaction</code> decrypts those transactions in full for each payment&#39;s value, output index and memo.</p>
<p>The good news for capacity planning is that the second fetch scales with <em>hits</em>, the payments you actually receive, and not with keys or chain volume. A full v6 transaction is a few kilobytes per action (our Lecture 1 specimen was 15,478 bytes for 4 actions), so even a busy backend fetches a modest amount. Budget it as one round trip per incoming payment, put a bounded worker pool in front of it, and make it idempotent on <code>(txid, output index)</code> because you will retry it.</p>
<p>The bad news is privacy, and it&#39;s the subject of Lecture 3. Asking the server for one specific transaction by txid tells the server which transaction you care about. The compact block stream was the same for every wallet, and the second fetch is not.</p>
<h2 id="9-sharding-the-scanner">9. Sharding the scanner</h2>
<p>With the cost model in hand, the scanner&#39;s architecture almost writes itself, but there are two different things you might shard, and they suit different jobs.</p>
<p><strong>Shard by keys for following the tip.</strong> Every worker reads the same block stream and owns a slice of the keys. Each worker&#39;s work per block is <code>(its keys) × 2 × A × t</code>, so you size slices so that a full block, <code>A = 330</code>, fits inside the block time with headroom. When a worker finds a hit, it emits <code>(account, txid, output index, value)</code> to the second-fetch pool, which feeds the ledger. One stream, many key slices.</p>
<p><strong>Shard by height for catching up.</strong> Rescans run over history, where the blocks are fixed and there&#39;s no deadline per block. Split the height range across workers and give each one every key that existed in its range. This is embarrassingly parallel, and it&#39;s how you bring a new auditor or a new worker up to the tip.</p>
<figure><img src="https://udokaam.dev/writing/one-viewing-key-a-million-customers/fig-08.png" alt="Fig 08. The lane's scanner: one block stream, key shards, and the second fetch" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 08. The scanner we&#39;ll build on through the series. The shard manager assigns keys to tip workers from measured trial throughput, and hits go to a separate, bounded second-fetch pool. Rescans run on their own height-range workers so a new auditor never slows the tip.</em></p>
<p>The shard manager is the makeshift component for this lecture, and its core is small enough to show. It takes your measured <code>t</code>, the number of accounts, the cores per worker and a headroom factor, and tells you how many workers you need for a full block:</p>
<div class="code-block" data-lang="python"><div class="code-head"><span class="code-lang">Python</span></div><pre><code class="language-python"><span class="hl-string">&quot;&quot;&quot;Size a sharded shielded scanner from your own measurements.&quot;&quot;&quot;</span>
<span class="hl-keyword">import</span> math, sys

BLOCK_SECONDS = <span class="hl-number">25</span>       <span class="hl-comment"># NU7 target spacing (ZIP 218)</span>
ACTION_CAP = <span class="hl-number">330</span>         <span class="hl-comment"># max shielded actions per block (ZIP 218)</span>
IVKS_PER_ACCOUNT = <span class="hl-number">2</span>     <span class="hl-comment"># external and internal (change) scope</span>

<span class="hl-keyword">def</span> <span class="hl-title function_">plan</span>(<span class="hl-params">accounts, us_per_trial, cores_per_worker=<span class="hl-number">4</span>, headroom=<span class="hl-number">0.5</span>, actions=ACTION_CAP</span>):
    <span class="hl-string">&quot;&quot;&quot;Workers needed so a full block is scanned within `headroom` of the block time.&quot;&quot;&quot;</span>
    trials = accounts * IVKS_PER_ACCOUNT * actions
    core_seconds = trials * us_per_trial / <span class="hl-number">1e6</span>
    budget = BLOCK_SECONDS * headroom * cores_per_worker   <span class="hl-comment"># core-seconds one worker gives a block</span>
    workers = <span class="hl-built_in">max</span>(<span class="hl-number">1</span>, math.ceil(core_seconds / budget))
    <span class="hl-keyword">return</span> {
        <span class="hl-string">&quot;core_seconds_per_full_block&quot;</span>: <span class="hl-built_in">round</span>(core_seconds, <span class="hl-number">2</span>),
        <span class="hl-string">&quot;workers&quot;</span>: workers,
        <span class="hl-string">&quot;accounts_per_worker&quot;</span>: math.ceil(accounts / workers),
    }

<span class="hl-keyword">if</span> __name__ == <span class="hl-string">&quot;__main__&quot;</span>:
    accounts = <span class="hl-built_in">int</span>(sys.argv[<span class="hl-number">1</span>]) <span class="hl-keyword">if</span> <span class="hl-built_in">len</span>(sys.argv) &gt; <span class="hl-number">1</span> <span class="hl-keyword">else</span> <span class="hl-number">500</span>
    us = <span class="hl-built_in">float</span>(sys.argv[<span class="hl-number">2</span>]) <span class="hl-keyword">if</span> <span class="hl-built_in">len</span>(sys.argv) &gt; <span class="hl-number">2</span> <span class="hl-keyword">else</span> <span class="hl-number">42.0</span>
    <span class="hl-built_in">print</span>(plan(accounts, us))</code></pre></div>
<p>With my 42 µs, 500 accounts fit in one four-core worker with half the block time to spare; 10,000 accounts need six workers of about 1,667 accounts each; a million accounts need 555. The headroom factor is a judgement call, and I use one half: a scanner that runs at 100% of the block time falls behind on the first slow block and never catches up, because there&#39;s no quiet period on a chain that keeps producing blocks.</p>
<h1>Part III: The lab</h1>
<h2 id="10-measure-the-chain-time-a-trial-issue-invoice-addresses">10. Measure the chain, time a trial, issue invoice addresses</h2>
<p>You need a Rust toolchain and Python 3. Both Rust programs run as examples inside sealForge&#39;s <code>sealforge-chain</code> crate, which already depends on everything they need, so from a clone of <a href="https://github.com/Udoka-AM/sealForge">sealForge</a>, save each one under <code>crates/sealforge-chain/examples/</code> and run it with <code>cargo run --release -p sealforge-chain --example &lt;name&gt;</code>. Use a release build; trial decryption in a debug build is many times slower and will make your capacity plan wildly pessimistic.</p>
<p><strong>Step 1: measure <code>A</code> and <code>t</code> on real blocks.</strong> This program streams the latest N compact blocks from a lightwallet server, counts what&#39;s in them, then times trial decryption of every Ironwood action against 1, 10 and 100 random keys, both one at a time and through the batch API. It&#39;s the program behind every number in sections 6 and 7.</p>
<div class="code-block" data-lang="rust"><div class="code-head"><span class="code-lang">Rust</span></div><pre><code class="language-rust"><span class="hl-comment">// scan_cost.rs. Usage: scan_cost &lt;url&gt; &lt;blocks&gt; [counts]</span>
<span class="hl-keyword">use</span> std::time::Instant;

<span class="hl-keyword">use</span> orchard::keys::{FullViewingKey, PreparedIncomingViewingKey, Scope, SpendingKey};
<span class="hl-keyword">use</span> orchard::note_encryption::{CompactAction, IronwoodVersion, NoteEncryptionDomain};
<span class="hl-keyword">use</span> prost::Message;
<span class="hl-keyword">use</span> sealforge_chain::connect;
<span class="hl-keyword">use</span> zcash_client_backend::proto::service::{BlockId, BlockRange, ChainSpec};

<span class="hl-meta">#[tokio::main]</span>
<span class="hl-keyword">async</span> <span class="hl-keyword">fn</span> <span class="hl-title function_">main</span>() <span class="hl-punctuation">-&gt;</span> anyhow::<span class="hl-type">Result</span>&lt;()&gt; {
    <span class="hl-keyword">let</span> <span class="hl-variable">url</span> = std::env::<span class="hl-title function_ invoke__">args</span>().<span class="hl-title function_ invoke__">nth</span>(<span class="hl-number">1</span>).<span class="hl-title function_ invoke__">unwrap</span>();
    <span class="hl-keyword">let</span> <span class="hl-variable">n</span>: <span class="hl-type">u64</span> = std::env::<span class="hl-title function_ invoke__">args</span>().<span class="hl-title function_ invoke__">nth</span>(<span class="hl-number">2</span>).<span class="hl-title function_ invoke__">unwrap</span>().<span class="hl-title function_ invoke__">parse</span>()?;
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">client</span> = <span class="hl-title function_ invoke__">connect</span>(&amp;url).<span class="hl-keyword">await</span>?;
    <span class="hl-keyword">let</span> <span class="hl-variable">tip</span> = client.<span class="hl-title function_ invoke__">get_latest_block</span>(ChainSpec::<span class="hl-title function_ invoke__">default</span>()).<span class="hl-keyword">await</span>?.<span class="hl-title function_ invoke__">into_inner</span>().height;
    <span class="hl-keyword">let</span> <span class="hl-variable">start</span> = tip - n + <span class="hl-number">1</span>;
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">stream</span> = client
        .<span class="hl-title function_ invoke__">get_block_range</span>(BlockRange {
            start: <span class="hl-title function_ invoke__">Some</span>(BlockId { height: start, hash: <span class="hl-built_in">vec!</span>[] }),
            end: <span class="hl-title function_ invoke__">Some</span>(BlockId { height: tip, hash: <span class="hl-built_in">vec!</span>[] }),
            pool_types: <span class="hl-built_in">vec!</span>[], <span class="hl-comment">// empty = shielded pools only</span>
        })
        .<span class="hl-keyword">await</span>?
        .<span class="hl-title function_ invoke__">into_inner</span>();

    <span class="hl-keyword">let</span> (<span class="hl-keyword">mut</span> blocks, <span class="hl-keyword">mut</span> bytes, <span class="hl-keyword">mut</span> outputs, <span class="hl-keyword">mut</span> max_in_block) = (<span class="hl-number">0u64</span>, <span class="hl-number">0u64</span>, <span class="hl-number">0u64</span>, <span class="hl-number">0u64</span>);
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">actions</span> = <span class="hl-type">Vec</span>::<span class="hl-title function_ invoke__">new</span>();
    <span class="hl-keyword">while</span> <span class="hl-keyword">let</span> <span class="hl-variable">Some</span>(b) = stream.<span class="hl-title function_ invoke__">message</span>().<span class="hl-keyword">await</span>? {
        blocks += <span class="hl-number">1</span>;
        bytes += b.<span class="hl-title function_ invoke__">encoded_len</span>() <span class="hl-keyword">as</span> <span class="hl-type">u64</span>;
        <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">per</span> = <span class="hl-number">0u64</span>;
        <span class="hl-keyword">for</span> <span class="hl-variable">tx</span> <span class="hl-keyword">in</span> &amp;b.vtx {
            per += (tx.actions.<span class="hl-title function_ invoke__">len</span>() + tx.ironwood_actions.<span class="hl-title function_ invoke__">len</span>() + tx.outputs.<span class="hl-title function_ invoke__">len</span>()) <span class="hl-keyword">as</span> <span class="hl-type">u64</span>;
            <span class="hl-keyword">for</span> <span class="hl-variable">a</span> <span class="hl-keyword">in</span> &amp;tx.ironwood_actions {
                <span class="hl-keyword">if</span> <span class="hl-keyword">let</span> <span class="hl-variable">Ok</span>(c) = CompactAction::<span class="hl-title function_ invoke__">try_from</span>(a) {
                    actions.<span class="hl-title function_ invoke__">push</span>(c);
                }
            }
        }
        outputs += per;
        max_in_block = max_in_block.<span class="hl-title function_ invoke__">max</span>(per);
    }
    <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;{blocks} blocks {start}..={tip}: {} compact bytes/block, {:.1} shielded outputs/block, max {max_in_block}&quot;</span>,
        bytes / blocks.<span class="hl-title function_ invoke__">max</span>(<span class="hl-number">1</span>), outputs <span class="hl-keyword">as</span> <span class="hl-type">f64</span> / blocks.<span class="hl-title function_ invoke__">max</span>(<span class="hl-number">1</span>) <span class="hl-keyword">as</span> <span class="hl-type">f64</span>);
    <span class="hl-keyword">if</span> std::env::<span class="hl-title function_ invoke__">args</span>().<span class="hl-title function_ invoke__">nth</span>(<span class="hl-number">3</span>).<span class="hl-title function_ invoke__">as_deref</span>() == <span class="hl-title function_ invoke__">Some</span>(<span class="hl-string">&quot;counts&quot;</span>) { <span class="hl-keyword">return</span> <span class="hl-title function_ invoke__">Ok</span>(()); }

    <span class="hl-keyword">for</span> <span class="hl-variable">k</span> <span class="hl-keyword">in</span> [<span class="hl-number">1usize</span>, <span class="hl-number">10</span>, <span class="hl-number">100</span>] {
        <span class="hl-keyword">let</span> <span class="hl-variable">ivks</span>: <span class="hl-type">Vec</span>&lt;PreparedIncomingViewingKey&gt; = (<span class="hl-number">0</span>..k)
            .<span class="hl-title function_ invoke__">map</span>(|i| {
                <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">seed</span> = [<span class="hl-number">7u8</span>; <span class="hl-number">32</span>];
                seed[..<span class="hl-number">8</span>].<span class="hl-title function_ invoke__">copy_from_slice</span>(&amp;(i <span class="hl-keyword">as</span> <span class="hl-type">u64</span> + <span class="hl-number">1</span>).<span class="hl-title function_ invoke__">to_le_bytes</span>());
                <span class="hl-keyword">let</span> <span class="hl-variable">sk</span> = <span class="hl-keyword">loop</span> {
                    <span class="hl-keyword">let</span> <span class="hl-variable">o</span>: <span class="hl-type">Option</span>&lt;SpendingKey&gt; = SpendingKey::<span class="hl-title function_ invoke__">from_bytes</span>(seed).<span class="hl-title function_ invoke__">into</span>();
                    <span class="hl-keyword">if</span> <span class="hl-keyword">let</span> <span class="hl-variable">Some</span>(sk) = o { <span class="hl-keyword">break</span> sk; }
                    seed[<span class="hl-number">31</span>] = seed[<span class="hl-number">31</span>].<span class="hl-title function_ invoke__">wrapping_add</span>(<span class="hl-number">1</span>);
                };
                PreparedIncomingViewingKey::<span class="hl-title function_ invoke__">new</span>(&amp;FullViewingKey::<span class="hl-title function_ invoke__">from</span>(&amp;sk).<span class="hl-title function_ invoke__">to_ivk</span>(Scope::External))
            })
            .<span class="hl-title function_ invoke__">collect</span>();
        <span class="hl-keyword">let</span> <span class="hl-variable">trials</span> = (k * actions.<span class="hl-title function_ invoke__">len</span>()) <span class="hl-keyword">as</span> <span class="hl-type">f64</span>;

        <span class="hl-keyword">let</span> <span class="hl-variable">t</span> = Instant::<span class="hl-title function_ invoke__">now</span>();
        <span class="hl-keyword">for</span> <span class="hl-variable">ivk</span> <span class="hl-keyword">in</span> &amp;ivks {
            <span class="hl-keyword">for</span> <span class="hl-variable">a</span> <span class="hl-keyword">in</span> &amp;actions {
                <span class="hl-keyword">let</span> <span class="hl-variable">d</span> = NoteEncryptionDomain::&lt;IronwoodVersion&gt;::<span class="hl-title function_ invoke__">for_compact_action</span>(a);
                <span class="hl-keyword">let</span> <span class="hl-variable">_</span> = zcash_note_encryption::<span class="hl-title function_ invoke__">try_compact_note_decryption</span>(&amp;d, ivk, a);
            }
        }
        <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;k={k:&gt;3} one at a time: {:.0} µs/trial&quot;</span>, t.<span class="hl-title function_ invoke__">elapsed</span>().<span class="hl-title function_ invoke__">as_secs_f64</span>() * <span class="hl-number">1e6</span> / trials);

        <span class="hl-keyword">let</span> <span class="hl-variable">outs</span>: <span class="hl-type">Vec</span>&lt;_&gt; = actions.<span class="hl-title function_ invoke__">iter</span>()
            .<span class="hl-title function_ invoke__">map</span>(|a| (NoteEncryptionDomain::&lt;IronwoodVersion&gt;::<span class="hl-title function_ invoke__">for_compact_action</span>(a), a.<span class="hl-title function_ invoke__">clone</span>()))
            .<span class="hl-title function_ invoke__">collect</span>();
        <span class="hl-keyword">let</span> <span class="hl-variable">t</span> = Instant::<span class="hl-title function_ invoke__">now</span>();
        <span class="hl-keyword">let</span> <span class="hl-variable">_</span> = zcash_note_encryption::batch::<span class="hl-title function_ invoke__">try_compact_note_decryption</span>(&amp;ivks, &amp;outs);
        <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;k={k:&gt;3} batch:        {:.0} µs/trial&quot;</span>, t.<span class="hl-title function_ invoke__">elapsed</span>().<span class="hl-title function_ invoke__">as_secs_f64</span>() * <span class="hl-number">1e6</span> / trials);
    }
    <span class="hl-title function_ invoke__">Ok</span>(())
}</code></pre></div>
<p>Run it against testnet first, because testnet&#39;s volume is smaller and the timing run finishes in a few minutes:</p>
<div class="code-block" data-lang="bash"><div class="code-head"><span class="code-lang">Bash</span></div><pre><code class="language-bash">cargo run --release -p sealforge-chain --example scan_cost -- https://testnet.zec.rocks:443 1000
cargo run --release -p sealforge-chain --example scan_cost -- https://zec.rocks:443 5000 counts</code></pre></div>
<p>The <code>counts</code> flag on the second line skips the timing, so you can survey mainnet without spending ten minutes decrypting it. Write down your batch <code>µs/trial</code> for 100 keys. That&#39;s your <code>t</code>.</p>
<p><strong>Step 2: issue invoice addresses from one account.</strong> This is the core of the makeshift checkout service: invoice number in, address out, and on detection, address back to invoice number, with nothing stored in between.</p>
<div class="code-block" data-lang="rust"><div class="code-head"><span class="code-lang">Rust</span></div><pre><code class="language-rust"><span class="hl-comment">// checkout.rs: one account, one diversified address per invoice.</span>
<span class="hl-keyword">use</span> std::time::Instant;
<span class="hl-keyword">use</span> orchard::keys::{FullViewingKey, Scope, SpendingKey};

<span class="hl-keyword">fn</span> <span class="hl-title function_">main</span>() {
    <span class="hl-keyword">let</span> <span class="hl-variable">sk</span>: SpendingKey = <span class="hl-type">Option</span>::&lt;SpendingKey&gt;::<span class="hl-title function_ invoke__">from</span>(SpendingKey::<span class="hl-title function_ invoke__">from_bytes</span>([<span class="hl-number">42u8</span>; <span class="hl-number">32</span>])).<span class="hl-title function_ invoke__">expect</span>(<span class="hl-string">&quot;valid key&quot;</span>);
    <span class="hl-keyword">let</span> <span class="hl-variable">ivk</span> = FullViewingKey::<span class="hl-title function_ invoke__">from</span>(&amp;sk).<span class="hl-title function_ invoke__">to_ivk</span>(Scope::External);

    <span class="hl-comment">// Invoice number -&gt; diversifier index -&gt; address. Nothing to store: the index is the invoice.</span>
    <span class="hl-keyword">let</span> <span class="hl-variable">t</span> = Instant::<span class="hl-title function_ invoke__">now</span>();
    <span class="hl-keyword">let</span> <span class="hl-variable">addrs</span>: <span class="hl-type">Vec</span>&lt;_&gt; = (<span class="hl-number">0u64</span>..<span class="hl-number">100_000</span>).<span class="hl-title function_ invoke__">map</span>(|invoice| ivk.<span class="hl-title function_ invoke__">address_at</span>(invoice)).<span class="hl-title function_ invoke__">collect</span>();
    <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;derived {} invoice addresses in {:?}&quot;</span>, addrs.<span class="hl-title function_ invoke__">len</span>(), t.<span class="hl-title function_ invoke__">elapsed</span>());

    <span class="hl-comment">// On detection, the decrypted note names its recipient address. Map it back to the invoice.</span>
    <span class="hl-keyword">let</span> <span class="hl-variable">paid</span> = &amp;addrs[<span class="hl-number">73_219</span>];
    <span class="hl-keyword">let</span> <span class="hl-variable">j</span> = ivk.<span class="hl-title function_ invoke__">diversifier_index</span>(paid).<span class="hl-title function_ invoke__">expect</span>(<span class="hl-string">&quot;ours&quot;</span>);
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">b</span> = [<span class="hl-number">0u8</span>; <span class="hl-number">8</span>];
    b.<span class="hl-title function_ invoke__">copy_from_slice</span>(&amp;j.<span class="hl-title function_ invoke__">as_bytes</span>()[..<span class="hl-number">8</span>]);
    <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;payment to invoice {}&quot;</span>, <span class="hl-type">u64</span>::<span class="hl-title function_ invoke__">from_le_bytes</span>(b));

    <span class="hl-comment">// Any address not derived from this key is rejected.</span>
    <span class="hl-keyword">let</span> <span class="hl-variable">other</span> = FullViewingKey::<span class="hl-title function_ invoke__">from</span>(&amp;<span class="hl-type">Option</span>::&lt;SpendingKey&gt;::<span class="hl-title function_ invoke__">from</span>(SpendingKey::<span class="hl-title function_ invoke__">from_bytes</span>([<span class="hl-number">9u8</span>; <span class="hl-number">32</span>])).<span class="hl-title function_ invoke__">unwrap</span>())
        .<span class="hl-title function_ invoke__">to_ivk</span>(Scope::External).<span class="hl-title function_ invoke__">address_at</span>(<span class="hl-number">0u64</span>);
    <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;foreign address recognised: {}&quot;</span>, ivk.<span class="hl-title function_ invoke__">diversifier_index</span>(&amp;other).<span class="hl-title function_ invoke__">is_some</span>());
}</code></pre></div>
<p>On my machine:</p>
<div class="code-block" data-lang="text"><div class="code-head"><span class="code-lang">Output</span></div><pre><code class="language-text">derived 100000 invoice addresses in 11.27s
payment to invoice 73219
foreign address recognised: false</code></pre></div>
<p>That&#39;s about 113 µs per address, so derive them on demand when an invoice is created rather than in bulk. <code>IncomingViewingKey::diversifier_index</code> decrypts the diversifier with FF1 and then re-derives the address to confirm it&#39;s really yours, which is why the foreign address comes back <code>false</code> instead of mapping to some random index. Never use a seed like <code>[42u8; 32]</code> for anything but this lab: a real account comes from a ZIP 32 seed you generated and stored properly.</p>
<p><strong>Step 3: size your scanner.</strong> Save the planner from section 9 as <code>plan_shards.py</code> and run it with your own <code>t</code>:</p>
<div class="code-block" data-lang="bash"><div class="code-head"><span class="code-lang">Bash</span></div><pre><code class="language-bash">python3 plan_shards.py 500 42
python3 plan_shards.py 10000 42</code></pre></div>
<div class="code-block" data-lang="text"><div class="code-head"><span class="code-lang">Output</span></div><pre><code class="language-text">{'core_seconds_per_full_block': 13.86, 'workers': 1, 'accounts_per_worker': 500}
{'core_seconds_per_full_block': 277.2, 'workers': 6, 'accounts_per_worker': 1667}</code></pre></div>
<p><strong>Exercises.</strong> Do these before Lecture 3; each one checks one of today&#39;s outcomes.</p>
<ol>
<li>Run Step 1 on your own machine and on the smallest cloud instance you&#39;d actually deploy to. How far apart are the two values of <code>t</code>, and what does that do to the worker count for 10,000 accounts?</li>
<li>Extend <code>scan_cost</code> to print the per-block output counts, then find the longest run of consecutive blocks above 250 outputs in the last 5,000 mainnet blocks. Would a scanner sized for the average have caught up by the end of that run? Show the arithmetic.</li>
<li>Corridor gives each (customer, period) its own vault. Design an alternative that gives the auditor the same one-customer, one-period view but watches fewer keys, and name what you had to give up. (Hint: think about what has to happen at the end of each period.)</li>
<li>Add a <code>Scope::Internal</code> key to <code>checkout.rs</code> and show that an internal address isn&#39;t recognised by the external key. Why would a backend that only ever receives still want to keep watching its internal key?</li>
</ol>
<h2 id="what-we-covered-and-where-we-go-next">What we covered, and where we go next</h2>
<p>Let&#39;s check off the outcomes.</p>
<p>You can explain why shielded detection costs grow with keys: the chain can&#39;t be indexed by address, so the wallet trial-decrypts every action with every key it holds, and each trial is one key agreement. You can issue a fresh, unlinkable address per invoice from one account and map a payment back to its invoice with the diversifier key. You know a CompactBlock gives the scanner 148 of each action&#39;s 820 bytes, and that the memo needs a second fetch per hit. You can price a scanner as <code>K × 2 × A × t</code> and size it for the 330-action cap rather than the average. And you know that choosing an account boundary chooses your scan bill, your disclosure unit and your auditor&#39;s view, all at once and for good.</p>
<p>Here are the numbers worth keeping in your head from today:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>What</th>
<th>Value</th>
<th>Source</th>
</tr>
</thead>
<tbody><tr>
<td>Work per block</td>
<td>accounts × 2 keys × actions × time per trial</td>
<td>Section 2</td>
</tr>
<tr>
<td>Time per trial</td>
<td>42 µs batched, 82 µs one at a time (one M3 Pro core)</td>
<td>Measured, lab Step 1</td>
</tr>
<tr>
<td>Max shielded actions per block</td>
<td>330 across all pools</td>
<td>ZIP 218</td>
</tr>
<tr>
<td>Shielded outputs per mainnet block</td>
<td>12.3 average, 0 median, 303 at p99</td>
<td>Measured, 5,000 blocks to 3,582,677</td>
</tr>
<tr>
<td>Compact action</td>
<td>148 bytes, against 820 for the full action</td>
<td><code>compact_formats.proto</code>, ZIP 229</td>
</tr>
<tr>
<td>Diversified addresses per account</td>
<td>2^88, all valid for the Orchard protocol</td>
<td>ZIP 32</td>
</tr>
<tr>
<td>Address derivation</td>
<td>about 113 µs per address</td>
<td>Measured, lab Step 2</td>
</tr>
<tr>
<td>Zebra address RPCs</td>
<td>10,000 addresses per request, 100,000 results</td>
<td><code>zebra-rpc/src/methods.rs</code></td>
</tr>
</tbody></table>
</div>
<p><strong>Next lecture: &quot;The indexer layer&quot;.</strong> Today we treated the compact block stream as given. Next time we look at the servers that produce it: how many wallets one indexer can serve, measured, now that Zaino and the zingod fork both exist, and what the server learns about each wallet from what it asks for, starting with the second fetch from section 8.</p>
<p>NOTE: Corridor&#39;s shielded lane and sealForge both run on Zcash testnet only. Neither has run on mainnet, and nothing here is financial advice. The timings are from one laptop and are a starting point, not a benchmark; measure on your own hardware before you size anything. Ecosystem facts are as of 17 November 2026 and checked against the sources below.</p>
<p>If you&#39;re running a shielded scanner at any scale, I&#39;d really like to compare numbers with you, and both repositories are open to contributors.</p>
<h2 id="references">References</h2>
<ul>
<li><a href="https://github.com/zcash/zips/blob/main/zips/zip-0218.md">ZIP 218: 25-second Block Target Spacing</a>, including the per-block action limits</li>
<li><a href="https://zips.z.cash/zip-0032">ZIP 32: Shielded Hierarchical Deterministic Wallets</a> and <a href="https://zips.z.cash/zip-0316">ZIP 316: Unified Addresses and Unified Viewing Keys</a></li>
<li><a href="https://zips.z.cash/zip-0229">ZIP 229: Version 6 Transaction Format</a></li>
<li><a href="https://zips.z.cash/protocol/protocol.pdf">Zcash protocol specification</a>: in-band secret distribution and key agreement for the Orchard protocol</li>
<li><a href="https://github.com/zcash/lightwallet-protocol/tree/main/walletrpc">compact_formats.proto and service.proto</a></li>
<li><a href="https://github.com/zcash/librustzcash">librustzcash</a>: <code>zcash_client_backend</code> scanning and <code>data_api::chain</code>, <code>zcash_note_encryption</code> (including the <code>batch</code> module), and the <code>orchard</code> crate&#39;s key types</li>
<li><a href="https://github.com/ZcashFoundation/zebra/blob/main/zebra-rpc/src/methods.rs">Zebra <code>zebra-rpc/src/methods.rs</code></a>: <code>MAX_REQUEST_ADDRESSES</code> and <code>MAX_ADDRESS_QUERY_RESULTS</code></li>
<li><a href="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/">Lecture 1: The Zcash stack after NU7</a></li>
<li><a href="https://github.com/Udoka-AM/corridor/blob/main/apps/docs/integrations/zcash.mdx">Corridor: the Zcash shielded lane</a> and <a href="https://github.com/Udoka-AM/sealForge">sealForge</a>, including <code>crates/sealforge-scan/src/lib.rs</code></li>
</ul>
]]></content:encoded>
    </item>
    <item>
      <title>The Zcash stack after NU7: from zcashd to an all-Rust system, and how one transaction is laid out across four pools</title>
      <link>https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/</link>
      <guid isPermaLink="true">https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/</guid>
      <pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Udoka A.M.</dc:creator>
      <category>zcash from the protocol up · lecture 1</category>
      <description>Lecture 1 of a ten-part engineering series. We follow one shielded payment through every program in today's Zcash stack, then take its 15,478 bytes apart field by field, on Zcash testnet.</description>
      <media:content url="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/cover.png" medium="image" />
      <content:encoded><![CDATA[<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/cover.png" alt="The Zcash stack after NU7, and one transaction laid out across four pools" width="4000" height="1600" loading="lazy" decoding="async"></figure>
<p><strong>If you sent one shielded payment on Zcash today, which programs would touch it, what would each of them see, and where in its bytes would the money actually be?</strong></p>
<p>That is the question we are going to answer in this lecture, and I want to answer it properly, the way you would want it answered if you were about to put a payments backend on top of this chain. By the end of the session you will be able to draw the whole stack from memory, point at the program that owns each job, and read a real Zcash transaction byte by byte with a short script you&#39;ve written and run yourself.</p>
<p><strong>Welcome to the first lecture of &quot;Zcash from the protocol up&quot;.</strong> This is a ten-part series for backend engineers who know distributed systems but have not worked on Zcash. Every lecture adds one working part to the same system, a shielded payout backend, so the series ends with something you can run rather than a pile of notes. The running example is the shielded lane I built for Corridor Finance, which pays suppliers privately on Zcash testnet and lets an auditor check one customer&#39;s payments with a viewing key. The contrast case, where the same Zcash parts are used under a different trust model, is sealForge, my sealed-bid auction system, also on testnet. I will bring both in where they are evidence for a point, never as the point itself.</p>
<p><strong>How this class works.</strong> I will teach the way I would at a whiteboard: a little history when it explains a design, then the mechanism, then something you can run. When I cite a rule, I cite the ZIP or the source file it comes from, so you can check me. Where something is still a draft or still moving, I will say so out loud, because Zcash changed more in 2026 than in any year before it and you deserve to know which parts are settled.</p>
<h2 id="what-i-expect-you-to-know-already">What I expect you to know already</h2>
<p>You do not need a cryptography background for this lecture. You need the working knowledge most backend engineers already carry, and I will show you exactly where each piece of it gets used.</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>You already know</th>
<th>Where we use it today</th>
</tr>
</thead>
<tbody><tr>
<td>Bitcoin-style transactions: inputs, outputs, fees, a UTXO set</td>
<td>Zcash&#39;s transparent pool is that model almost unchanged, and the shielded pools are built as a contrast to it</td>
</tr>
<tr>
<td>Hashes and Merkle trees</td>
<td>Every shielded output becomes a leaf in a note commitment tree, and every spend proves membership against a root</td>
</tr>
<tr>
<td>Public-key signatures</td>
<td>Each shielded spend carries a signature, and each pool carries a &quot;binding&quot; signature that proves the amounts balance</td>
</tr>
<tr>
<td>Client/server systems, JSON-RPC and gRPC</td>
<td>The stack is a set of services that talk over exactly these protocols</td>
</tr>
<tr>
<td>Reading little-endian integers and variable-length fields</td>
<td>The dissection in Part II is nothing more than this, done carefully</td>
</tr>
<tr>
<td>Docker, and reading a little Rust and Python</td>
<td>The lab at the end runs a local chain and two short programs</td>
</tr>
</tbody></table>
</div>
<p>What you do <strong>not</strong> need: elliptic-curve arithmetic, the inner workings of Halo 2, or how a zk-SNARK circuit is written. We will treat the proof as a black box with a known size and a known job, which is exactly how a backend treats it in production. Later lectures open some of those boxes when a design decision depends on what is inside.</p>
<p><strong>What you will be able to do by the end.</strong> Five outcomes, and I will check them off as we go:</p>
<ol>
<li>Name each program in the post-NU7 stack, what it owns, and how your backend should talk to it.</li>
<li>Trace one shielded payment from the wallet that builds it to the wallet that finds it.</li>
<li>Read a v6 transaction header and say which network upgrade it was built for.</li>
<li>Explain what each of the 820 bytes in a shielded action is for, and who can read them.</li>
<li>Explain how the chain counts money it cannot see, and why that mattered so much in 2026.</li>
</ol>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-01.png" alt="Fig 01. The ten-lecture map, with today's lecture highlighted" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 01. The series map. Today is the ground floor: the stack and the transaction. Everything after this builds on the vocabulary we set up here.</em></p>
<h1>Part I: The stack</h1>
<h2 id="1-a-short-history-in-five-upgrades-and-one-bug">1. A short history in five upgrades and one bug</h2>
<p>I always start with history, because almost every odd-looking detail in Zcash is a scar from a specific decision, and once you know which decision, the detail stops looking odd.</p>
<p>Zcash launched in 2016 with one shielded pool, <strong>Sprout</strong>. In 2018 the <strong>Sapling</strong> upgrade introduced a far more efficient second pool, and in 2019 <strong>Blossom</strong> halved the block target spacing from 150 seconds to 75 seconds. In 2022, <strong>NU5</strong> brought the third shielded pool, <strong>Orchard</strong>, built on the Halo 2 proof system, which needs no trusted setup, together with the version 5 transaction format (ZIP 225) and unified addresses (ZIP 316). For three years after that, if someone said &quot;shielded Zcash&quot;, they mostly meant Orchard.</p>
<p>Then came 2026. On 29 May, security researcher Taylor Hornby, who had been asked to run an AI-assisted audit of the Orchard protocol, reported a soundness vulnerability in the Orchard Action circuit implementation. ZIP 257 records the response in plain terms: the bug &quot;could have allowed balance violation and theft of funds&quot;, so use of Orchard was disabled immediately, and a corrected circuit was deployed in the <strong>NU6.2</strong> upgrade [ZIP 257].</p>
<p>Fixing the circuit closed the hole, but it didn&#39;t by itself restore confidence in the money already sitting in Orchard, and that is what <strong>NU6.3</strong> was for. It introduced a fourth shielded pool, <strong>Ironwood</strong>, activated on mainnet at height 3,428,143 [ZIP 258]. Ironwood reuses the Orchard protocol almost unchanged, but it starts with a clean state, its supply integrity was backed by formal verification from the start, and every note in it is <em>quantum-recoverable</em>: if discrete-log cryptography ever has to be switched off, a recovery protocol can still return Ironwood funds to their owners [ZIP 229, ZIP 2005]. At the same moment, the Orchard pool was sealed: value can leave it, but it cannot enter it, and an Orchard action may only send to the same address as the note it spends [ZIP 2006]. The practical effect is a one-way door from Orchard into Ironwood.</p>
<p>The most recent upgrade, <strong>NU7</strong>, activated on mainnet at height 3,543,405 in November 2026 [Zebra 7.0.0 release]. It cut the block target spacing again, from 75 seconds to 25 seconds (ZIP 218), introduced per-block limits on shielded actions, and made version 4 transactions invalid. That last change quietly finishes Sprout: Sprout spends only exist in the v4 format, so once v4 is gone, Sprout funds have no transaction that can move them.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-02.png" alt="Fig 02. Zcash's pools and upgrades on one timeline" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 02. Four shielded pools, each born at an upgrade. Orchard is now exit-only; new shielded value lands in Ironwood.</em></p>
<p>Hold on to one idea from this history, because it will come back three times today: <strong>Zcash keeps each pool&#39;s books separately.</strong> That design is what let the network contain a counterfeiting bug in one pool without having to doubt the others.</p>
<h2 id="2-from-one-process-to-five-components">2. From one process to five components</h2>
<p>For most of Zcash&#39;s life there was one program at the centre of everything: <strong>zcashd</strong>, a C++ codebase descended from Bitcoin Core. It was the consensus node, the wallet and the RPC server in one process. If you ran an exchange, a block explorer or a mining pool, you ran zcashd. Its repository is now archived.</p>
<p>Its jobs have been split across separate, mostly Rust, components. This is the single biggest change for anyone building on Zcash, so let&#39;s go through them one at a time.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-03.png" alt="Fig 03. From the zcashd monolith to the post-NU7 stack" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 03. The left side is what a Zcash backend looked like for years. The right side is what you deploy now, with each component&#39;s owner and the protocol your code uses to reach it.</em></p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Component</th>
<th>Its job</th>
<th>Maintained by</th>
<th>How your backend reaches it</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Zebra</strong> (<code>zebrad</code>)</td>
<td>Consensus node: validates blocks and transactions, keeps chain state, serves JSON-RPC</td>
<td>Zcash Foundation</td>
<td>JSON-RPC; Zebra 7.0.0 was the first stable NU7 release</td>
</tr>
<tr>
<td><strong>Zakura</strong></td>
<td>A second consensus node, forked from Zebra and tuned for performance, with pruning, snapshots and a zcashd-compatible RPC mode</td>
<td>Valar Group, with Project Tachyon</td>
<td>JSON-RPC</td>
</tr>
<tr>
<td><strong>Indexer</strong> (lightwalletd, Zaino, zingod)</td>
<td>Turns full blocks into <em>compact blocks</em> and serves them, plus transaction lookup and submission, over the CompactTxStreamer gRPC service</td>
<td>lightwalletd: ZODL. Zaino: the Zaino project. zingod: Zingo Labs, which left Zaino in November 2026 and now maintains this fork</td>
<td>gRPC (CompactTxStreamer)</td>
</tr>
<tr>
<td><strong>Zallet</strong></td>
<td>A full-node wallet with a zcashd-style RPC, built to replace the zcashd wallet; currently in beta</td>
<td>ZODL</td>
<td>JSON-RPC</td>
</tr>
<tr>
<td><strong>librustzcash</strong></td>
<td>The Rust libraries every modern wallet is built on: keys, addresses, transaction building, scanning, PCZT</td>
<td>ZODL</td>
<td>A library you link, not a service</td>
</tr>
</tbody></table>
</div>
<p>There is also a repository called Z3 whose stated purpose is the &quot;grand unification of Zebra, Zaino and Zallet&quot; into one deployable stack, which tells you where the ecosystem expects most operators to land.</p>
<p><strong>Why the split matters to a backend engineer.</strong> Three consequences, and each of them will become a design rule later in the series.</p>
<p>First, these are separate scaling tiers and separate failure domains. A wallet service that serves ten thousand customers puts its load on the indexer, not the node, and an indexer that falls behind does not stop the node from validating. You size and monitor them separately.</p>
<p>Second, they upgrade on different schedules, and the gaps are real. Zebra 7.0.0 moved its state database to format v29, which earlier versions cannot read, so tools that read Zebra&#39;s state directly have to upgrade in the same window. My own sealForge regtest configuration leaves NU7 switched off for exactly this reason: the Zaino version it pins did not yet know NU7&#39;s consensus branch ID. When you run this stack, the slowest component sets your upgrade date.</p>
<p>Third, there are now two consensus implementations. That is healthy for the network and a new responsibility for you. In October and November 2026 the two nodes disagreed on the standard fee per logical action (Zakura used 400 zatoshis while Zebra used the ZIP 317 value) until Zakura moved to 1,000, and transactions could stop relaying between them in the meantime. Lecture 8 is about building a gateway that notices this kind of divergence before your customers do.</p>
<h2 id="3-follow-one-payment-through-the-stack">3. Follow one payment through the stack</h2>
<p>Now let&#39;s make the diagram move. Here is the life of one shielded payment, the one we are going to dissect in Part II, from the wallet that builds it to the wallet that receives it.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-04.png" alt="Fig 04. One shielded payment through the stack, step by step" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 04. Eight steps from build to discovery. Notice that the recipient never talks to the node: it learns about its payment from compact blocks served by an indexer.</em></p>
<ol>
<li><strong>Build.</strong> The sender&#39;s wallet selects notes it owns, picks an anchor (a recent root of the note commitment tree), creates the outputs and their encrypted memos, and produces the zero-knowledge proof. In Corridor&#39;s lane this is a PCZT, a partially constructed transaction, passed through create, prove, sign and combine stages (ZIP 374). Lecture 6 is entirely about that pipeline.</li>
<li><strong>Submit.</strong> The finished transaction goes to an indexer&#39;s <code>SendTransaction</code> gRPC method, or straight to a node&#39;s <code>sendrawtransaction</code> RPC.</li>
<li><strong>Verify for the mempool.</strong> The node checks the proof, every signature, that the anchor is a real past root, that no nullifier has been spent before, and that the fee meets policy. Only then does it enter the mempool.</li>
<li><strong>Gossip.</strong> The node relays it to peers. This is where a fee-policy disagreement between implementations can strand a transaction.</li>
<li><strong>Mine.</strong> A miner&#39;s block template includes it. Our specimen was mined at testnet height 4,412,453 in a block with exactly two transactions: the coinbase and our payment.</li>
<li><strong>Commit.</strong> Every node that accepts the block appends the new note commitments to the pool&#39;s tree, adds the nullifiers to the spent set, and updates the pool&#39;s value balance. Keep that last part in mind, we come back to it in section 9.</li>
<li><strong>Index.</strong> The indexer reduces the block to a compact block: just the fields a wallet needs to detect its own payments.</li>
<li><strong>Discover.</strong> The recipient&#39;s wallet downloads compact blocks, tries to decrypt each output with its viewing key, and finds the one meant for it. Because compact blocks leave memos out, it then fetches the full transaction to read the memo.</li>
</ol>
<p>Step 8 is where most of a wallet backend&#39;s cost lives, and it is the subject of Lecture 2. For today, the point is simpler: there is no step where the recipient asks the node &quot;do I have money?&quot; Discovery is trial decryption over a stream, and that is a very different scaling problem from querying an address index.</p>
<h1>Part II: The transaction</h1>
<h2 id="4-meet-our-specimen">4. Meet our specimen</h2>
<p>Our specimen is a real transaction on Zcash <strong>testnet</strong>:</p>
<div class="code-block" data-lang="text"><div class="code-head"><span class="code-lang">Output</span></div><pre><code class="language-text">txid    de5d25625a372d6d79d0b071f0727cdcf8a8718c48d69057fd060825c09d4a7b
height  4,412,453 (testnet)
size    15,478 bytes</code></pre></div>
<p>It is the first batch the Corridor shielded lane ever settled: one transaction paying three suppliers, each with an encrypted invoice memo, which an auditor later matched three out of three using only a viewing key. I chose it because it is small enough to read in a lecture and real enough to have the awkward details that synthetic examples hide.</p>
<p>I fetched the raw bytes from a public lightwallet server with a few lines of Rust, using the <code>GetTransaction</code> call from step 8 of Fig 04 (the full program is in the lab), and parsed them with a short Python script that follows the v6 layout in ZIP 229 field by field. Everything in this part comes from those bytes. You will reproduce all of it yourself at the end.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-05.png" alt="Fig 05. The 15,478 bytes of our specimen, drawn to scale" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 05. The whole transaction drawn to scale. Three quarters of it is one proof.</em></p>
<p>Before we zoom in, take a second with the proportions in Fig 05, because they teach the first lesson about cost. The header and counters are 26 bytes. The four shielded actions are 3,280 bytes. The proof is 11,808 bytes, 76% of everything. So if anyone asks you why shielded transactions are so much larger than transparent ones, the honest one-line answer is that it&#39;s mostly the proof.</p>
<h2 id="5-reading-the-header-twenty-bytes-that-pin-the-rules">5. Reading the header: twenty bytes that pin the rules</h2>
<p>The first twenty bytes are the same in every v6 transaction, and they tell a node which rulebook to apply. All integers are little-endian, so read each group of hex digits right to left.</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Offset</th>
<th>Bytes</th>
<th>Field</th>
<th>Raw hex</th>
<th>Decoded</th>
</tr>
</thead>
<tbody><tr>
<td>0</td>
<td>4</td>
<td><code>header</code></td>
<td><code>06000080</code></td>
<td>0x80000006: the top bit is <code>fOverwintered</code>, always set; the low bits are version <strong>6</strong></td>
</tr>
<tr>
<td>4</td>
<td>4</td>
<td><code>nVersionGroupId</code></td>
<td><code>98b684d8</code></td>
<td>0xD884B698, the value ZIP 229 requires for v6</td>
</tr>
<tr>
<td>8</td>
<td>4</td>
<td><code>nConsensusBranchId</code></td>
<td><code>5b16a537</code></td>
<td>0x37A5165B, the <strong>NU6.3</strong> branch ID from ZIP 258</td>
</tr>
<tr>
<td>12</td>
<td>4</td>
<td><code>lock_time</code></td>
<td><code>00000000</code></td>
<td>0, no time lock</td>
</tr>
<tr>
<td>16</td>
<td>4</td>
<td><code>nExpiryHeight</code></td>
<td><code>4a544300</code></td>
<td>4,412,490</td>
</tr>
</tbody></table>
</div>
<p>Two of these deserve a pause.</p>
<p><strong>The consensus branch ID is a promise about which rules the signer agreed to.</strong> It is part of what gets signed, so a transaction built for NU6.3 cannot be replayed under different rules. That safety property has a cost every wallet team feels: each network upgrade changes the branch ID, so every wallet has to ship a release, even when the transaction format itself does not change. NU7 did exactly that, moving the branch ID to 0x77190AD9. Lecture 9 looks at ZIP 248, the draft that tries to stop upgrades from breaking wallets this way.</p>
<p><strong>The expiry height is a deadline, and here it tells a small story.</strong> librustzcash builds transactions with a default expiry delta of 40 blocks, so this one was built when the chain&#39;s next block was 4,412,450, and it was mined at 4,412,453, three blocks later. Had it sat in the mempool past 4,412,490, nodes would have dropped it. For a payments backend this is a gift: a transaction that has not been mined by its expiry height never will be, so &quot;pending&quot; has a hard upper bound, and your retry logic can be exact instead of hopeful.</p>
<h2 id="6-four-pools-six-counters">6. Four pools, six counters</h2>
<p>The next six bytes are the most compact summary of the transaction you will ever see.</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Offset</th>
<th>Field</th>
<th>Value</th>
<th>Meaning</th>
</tr>
</thead>
<tbody><tr>
<td>20</td>
<td><code>tx_in_count</code></td>
<td>0</td>
<td>No transparent inputs</td>
</tr>
<tr>
<td>21</td>
<td><code>tx_out_count</code></td>
<td>0</td>
<td>No transparent outputs</td>
</tr>
<tr>
<td>22</td>
<td><code>nSpendsSapling</code></td>
<td>0</td>
<td>No Sapling spends</td>
</tr>
<tr>
<td>23</td>
<td><code>nOutputsSapling</code></td>
<td>0</td>
<td>No Sapling outputs</td>
</tr>
<tr>
<td>24</td>
<td><code>nActionsOrchard</code></td>
<td>0</td>
<td>No Orchard actions</td>
</tr>
<tr>
<td>25</td>
<td><code>nActionsIronwood</code></td>
<td>4</td>
<td>Four Ironwood actions</td>
</tr>
</tbody></table>
</div>
<p>A v6 transaction has a section for every pool: transparent, Sapling, Orchard and Ironwood. Each section starts with a count, and when the count is zero, everything else in that section is simply absent. That is why a transaction that touches only Ironwood pays just five bytes for the three pools it ignores [ZIP 229, Transaction Format, notes † ‡ § ◊].</p>
<p>For contrast, here is the other transaction in the same block, the coinbase that paid the miner: one transparent input, two transparent outputs, and zeros everywhere else, 181 bytes in all. Its expiry height is exactly the block height, 4,412,453, which is the rule for coinbase transactions. Its input script even carries the mining pool&#39;s ASCII tag, <code>Foundry Zcash Pool #PrivacyMatters</code>. Same format, same header, entirely different shape: the format is a set of optional pool sections, and each transaction fills in the ones it uses.</p>
<p>You might be wondering why three suppliers needed four actions. The thing to unlearn here is that an action equals one payment, because it doesn&#39;t. <strong>An action is a slot that can spend one note and create one note at the same time.</strong> Three of the new notes go to the suppliers; the fourth is change returning to the vault. Where an action has nothing real to spend, the wallet fills the spend side with a dummy, so from outside every action looks the same. That uniformity is deliberate: an observer cannot count real spends or real recipients from the action count alone, only bound them.</p>
<h2 id="7-inside-one-action-820-bytes-and-who-can-read-them">7. Inside one action: 820 bytes and who can read them</h2>
<p>Every Orchard-protocol action, in Orchard or Ironwood, is exactly 820 bytes, in seven fields. Here is action 0 of our specimen.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-06.png" alt="Fig 06. The anatomy of one 820-byte action, and who can read each part" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 06. Seven fields. Everyone can see all 820 bytes; the colour shows who can make sense of them.</em></p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Field</th>
<th>Bytes</th>
<th>What it is</th>
<th>Who can make use of it</th>
</tr>
</thead>
<tbody><tr>
<td><code>cv</code></td>
<td>32</td>
<td>A commitment to the value moving through this action. It hides the amount but can be added to other commitments</td>
<td>Everyone, but only in sums: this is how the binding signature proves the books balance</td>
</tr>
<tr>
<td><code>nullifier</code></td>
<td>32</td>
<td>A unique marker for the note being spent</td>
<td>Every node stores it; a second use of the same nullifier is a double spend and is rejected. Only the owner could have computed it, and it cannot be linked back to the note it spends</td>
</tr>
<tr>
<td><code>rk</code></td>
<td>32</td>
<td>A randomized public key for this spend</td>
<td>Nodes use it to check the spend authorization signature</td>
</tr>
<tr>
<td><code>cmx</code></td>
<td>32</td>
<td>The commitment to the newly created note</td>
<td>Appended to the pool&#39;s note commitment tree. It is the leaf a future spend will prove membership against</td>
</tr>
<tr>
<td><code>ephemeralKey</code></td>
<td>32</td>
<td>A one-time public key for this output</td>
<td>The recipient combines it with their viewing key to derive the decryption key</td>
</tr>
<tr>
<td><code>encCiphertext</code></td>
<td>580</td>
<td>The encrypted note: recipient, value, randomness and a <strong>512-byte memo</strong>, plus a 16-byte tag</td>
<td>The recipient, or anyone holding their incoming viewing key</td>
</tr>
<tr>
<td><code>outCiphertext</code></td>
<td>80</td>
<td>Lets the sender recover what they sent</td>
<td>The sender, with their outgoing viewing key</td>
</tr>
</tbody></table>
</div>
<p>Look at where the money is. The value appears twice: committed in <code>cv</code> and encrypted inside <code>encCiphertext</code>. Neither is readable by a chain observer, yet the chain can still check that the transaction balances, because value commitments add up and the binding signature proves the total equals the declared value balance. This is the second appearance of today&#39;s big idea: the chain does arithmetic on amounts it cannot see.</p>
<p>Look also at the 512-byte memo inside the 580-byte ciphertext. That is where Corridor puts its invoice reference, <code>INV-… / corridor:&lt;ref&gt;</code>, and where sealForge puts its bid commitment. It is also why, in step 8 of Fig 04, the recipient has to fetch the full transaction: a compact block keeps only the nullifier, <code>cmx</code>, <code>ephemeralKey</code> and the first 52 bytes of <code>encCiphertext</code>, which is enough to detect a payment and learn its value, and drops the memo to stay small. Lecture 4 treats that memo as a reconciliation key and designs the format carefully.</p>
<h2 id="8-the-bundle-trailer-flags-balance-anchor-proof-and-signatures">8. The bundle trailer: flags, balance, anchor, proof and signatures</h2>
<p>After the four actions come the fields that apply to the Ironwood bundle as a whole.</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>Offset</th>
<th>Bytes</th>
<th>Field</th>
<th>Value in our specimen</th>
</tr>
</thead>
<tbody><tr>
<td>3,306</td>
<td>1</td>
<td><code>flagsIronwood</code></td>
<td><code>0x07</code>: <code>enableSpends</code>, <code>enableOutputs</code> and <code>enableCrossAddress</code> all set</td>
</tr>
<tr>
<td>3,307</td>
<td>8</td>
<td><code>valueBalanceIronwood</code></td>
<td><strong>+20,000</strong> zatoshis</td>
</tr>
<tr>
<td>3,315</td>
<td>32</td>
<td><code>anchorIronwood</code></td>
<td>The root of the Ironwood note commitment tree that every spend in this bundle proves against</td>
</tr>
<tr>
<td>3,347</td>
<td>3</td>
<td><code>sizeProofsIronwood</code></td>
<td>11,808 (a CompactSize: <code>fd</code> followed by a two-byte length)</td>
</tr>
<tr>
<td>3,350</td>
<td>11,808</td>
<td><code>proofsIronwood</code></td>
<td>One aggregated Halo 2 proof for all four actions</td>
</tr>
<tr>
<td>15,158</td>
<td>256</td>
<td><code>vSpendAuthSigsIronwood</code></td>
<td>Four 64-byte spend authorization signatures, one per action</td>
</tr>
<tr>
<td>15,414</td>
<td>64</td>
<td><code>bindingSigIronwood</code></td>
<td>One binding signature for the bundle</td>
</tr>
</tbody></table>
</div>
<p>Three of these are worth your full attention.</p>
<p><strong>The flags byte carries a 2026 scar.</strong> <code>enableCrossAddress</code> is new at NU6.3. In the Orchard pool it must be zero, which is how the circuit enforces the seal from section 1: an Orchard action can only send to the address it spends from. In Ironwood it is set, because sending to other people is the whole point [ZIP 229, ZIP 2006].</p>
<p><strong>The value balance is the fee, and you can check it.</strong> <code>valueBalanceIronwood</code> is the net value leaving the Ironwood pool: spends minus outputs. Here that is +20,000 zatoshis. With no transparent outputs and no other pools involved, value leaving the shielded pool has only one place to go, the fee. Now check it against ZIP 317, which charges a marginal fee of 5,000 zatoshis per logical action with a floor of two &quot;grace&quot; actions: 5,000 × max(2, 4) = 20,000. And remember that our specimen shared its block only with the coinbase: the miner&#39;s output in that coinbase is 125,020,000 zatoshis, and the trailing 20,000 is our fee arriving on the other side. You have just followed a fee from one transaction into another.</p>
<p><strong>The proof size is a formula, not a measurement.</strong> ZIP 229 fixes it at 2,720 + 2,272 × n bytes for n actions, so four actions give 11,808 bytes, exactly what we read. For capacity planning that&#39;s genuinely useful, because a shielded transaction&#39;s size is predictable from its action count before you build it. It also explains why ZIP 317 prices by action and not by byte, and why NU7&#39;s new limits count shielded actions per block rather than bytes.</p>
<p>One more observation, and it is my favourite in the whole dissection. Corridor&#39;s lane also settled a batch from a <strong>FROST 2-of-3 vault</strong>, where no single server holds the spending key and two of three signers must cooperate (testnet transaction <code>878b44b8…</code>). I ran it through the same script. It is also 15,478 bytes, also four Ironwood actions, also a +20,000 fee, and its signatures are ordinary 64-byte signatures. Threshold custody leaves no trace in the transaction: the chain cannot tell a 2-of-3 vault from a single key. That is a privacy property and an operational one, and Lecture 6 builds on it.</p>
<h2 id="9-how-the-chain-counts-money-it-cannot-see">9. How the chain counts money it cannot see</h2>
<p>Now we can close the loop on the idea I asked you to hold since the history section.</p>
<p>Every node keeps a running balance for each pool. For a shielded pool, it is the negation of the sum of every <code>valueBalance</code> field ever accepted into that pool [ZIP 209]. Our specimen moved Ironwood&#39;s balance down by 20,000 zatoshis, the fee leaving the pool. The rule that makes this a safety mechanism is short: if accepting a block would make any pool&#39;s balance negative, or push the total supply above the maximum, every node must reject the block [ZIP 209].</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-07.png" alt="Fig 07. Per-pool accounting: the turnstile that bounds the damage of a broken pool" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 07. Each pool is a separately audited account. Value crosses between pools in the open, so even a counterfeiting bug inside one pool cannot withdraw more than was ever deposited into it.</em></p>
<p>Think about what that means in May 2026. Suppose someone had used the Orchard soundness bug to create notes from nothing. Inside Orchard those fake notes would be indistinguishable from real ones, because that is what a privacy protocol does. But to take value <em>out</em> of Orchard, they would have to cross the turnstile, and the turnstile would refuse to let Orchard&#39;s public balance go below zero. Counterfeiting inside one pool cannot inflate the total supply. That is why the network could respond by sealing one pool and opening a fresh one, rather than doubting all of Zcash.</p>
<p>The turnstile has a price, and as engineers we should name it. Amounts that cross between pools are public. ZIP 229 says so directly: the turnstile &quot;reveals the amounts in each transaction that cross between pools, including the amounts migrated into the Ironwood pool&quot; [ZIP 229, Privacy Implications]. Our specimen leaks exactly one number, its fee, because nothing else crossed. A transaction that migrates funds from Orchard into Ironwood, or shields from transparent, leaks the amount it moves. A backend that wants to stay private keeps its money inside one shielded pool and crosses rarely, in amounts that do not identify anyone. Lecture 5 turns that into a payout design.</p>
<h1>Part III: The lab</h1>
<h2 id="10-run-the-stack-and-dissect-a-transaction-yourself">10. Run the stack and dissect a transaction yourself</h2>
<p>Reading about bytes is not the same as reading bytes, so let&#39;s finish at the keyboard. You need Docker, a Rust toolchain and Python 3.</p>
<figure><img src="https://udokaam.dev/writing/zcash-stack-after-nu7-one-transaction-four-pools/fig-08.png" alt="Fig 08. The lab: a local regtest chain and the two tools we use on it" width="3200" height="2000" loading="lazy" decoding="async"></figure>
<p><em>Fig 08. What you will have running at the end of the lab. Zebra in regtest mode with every upgrade through NU6.3 active from block 1, Zaino serving compact blocks over gRPC, and your two tools pointed at it, or at a public testnet server.</em></p>
<p><strong>Step 1: start a private chain.</strong> sealForge ships a regtest setup that runs Zebra with no peers and no proof of work, so blocks are mined on demand. From a clone of <a href="https://github.com/Udoka-AM/sealForge">sealForge</a>:</p>
<div class="code-block" data-lang="bash"><div class="code-head"><span class="code-lang">Bash</span></div><pre><code class="language-bash">scripts/regtest.sh up &lt;your-miner-unified-address&gt;   <span class="hl-comment"># Zebra + Zaino</span>
scripts/regtest.sh mine 101                          <span class="hl-comment"># coinbase matures after 100 blocks</span>
scripts/regtest.sh height</code></pre></div>
<p>Then ask the indexer what it thinks the chain is. This is the same health check I run before pointing anything at a new server:</p>
<div class="code-block" data-lang="bash"><div class="code-head"><span class="code-lang">Bash</span></div><pre><code class="language-bash">cargo run -p sealforge-chain --example probe_lightwalletd -- http://127.0.0.1:8137</code></pre></div>
<p>It prints the chain name, the tip height and the consensus branch ID the server is on. Run it against <code>https://testnet.zec.rocks:443</code> too, and compare.</p>
<p><strong>Step 2: fetch raw transaction bytes.</strong> This is the program I used for the specimen. It asks a lightwallet server for one transaction by id and prints the raw hex. Note the <code>reverse()</code>: transaction ids are displayed byte-reversed, the same convention Bitcoin uses.</p>
<div class="code-block" data-lang="rust"><div class="code-head"><span class="code-lang">Rust</span></div><pre><code class="language-rust"><span class="hl-keyword">use</span> zcash_client_backend::proto::service::TxFilter;

<span class="hl-meta">#[tokio::main]</span>
<span class="hl-keyword">async</span> <span class="hl-keyword">fn</span> <span class="hl-title function_">main</span>() <span class="hl-punctuation">-&gt;</span> anyhow::<span class="hl-type">Result</span>&lt;()&gt; {
    <span class="hl-keyword">let</span> <span class="hl-variable">url</span> = std::env::<span class="hl-title function_ invoke__">args</span>().<span class="hl-title function_ invoke__">nth</span>(<span class="hl-number">1</span>).<span class="hl-title function_ invoke__">unwrap</span>();
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">txid</span> = hex::<span class="hl-title function_ invoke__">decode</span>(std::env::<span class="hl-title function_ invoke__">args</span>().<span class="hl-title function_ invoke__">nth</span>(<span class="hl-number">2</span>).<span class="hl-title function_ invoke__">unwrap</span>())?;
    txid.<span class="hl-title function_ invoke__">reverse</span>(); <span class="hl-comment">// displayed txids are byte-reversed</span>
    <span class="hl-keyword">let</span> <span class="hl-keyword">mut </span><span class="hl-variable">client</span> = sealforge_chain::<span class="hl-title function_ invoke__">connect</span>(&amp;url).<span class="hl-keyword">await</span>?;
    <span class="hl-keyword">let</span> <span class="hl-variable">raw</span> = client
        .<span class="hl-title function_ invoke__">get_transaction</span>(TxFilter { block: <span class="hl-literal">None</span>, index: <span class="hl-number">0</span>, hash: txid })
        .<span class="hl-keyword">await</span>?
        .<span class="hl-title function_ invoke__">into_inner</span>();
    <span class="hl-built_in">println!</span>(<span class="hl-string">&quot;height {}\n{}&quot;</span>, <span class="hl-keyword">raw</span>.height, hex::<span class="hl-title function_ invoke__">encode</span>(&amp;<span class="hl-keyword">raw</span>.data));
    <span class="hl-title function_ invoke__">Ok</span>(())
}</code></pre></div>
<p><strong>Step 3: dissect it.</strong> Here is the whole dissector. It follows the ZIP 229 table top to bottom, asserts every structural rule it can (the version group ID, the proof-size formula, no trailing bytes), and prints each field with its offset.</p>
<div class="code-block" data-lang="python"><div class="code-head"><span class="code-lang">Python</span></div><pre><code class="language-python"><span class="hl-string">&quot;&quot;&quot;Dissect a Zcash v6 (NU6.3+) transaction, field by field, per ZIP 229.&quot;&quot;&quot;</span>
<span class="hl-keyword">import</span> struct, sys

<span class="hl-keyword">class</span> <span class="hl-title class_">Reader</span>:
    <span class="hl-keyword">def</span> <span class="hl-title function_">__init__</span>(<span class="hl-params">self, raw</span>): <span class="hl-variable language_">self</span>.b, <span class="hl-variable language_">self</span>.p, <span class="hl-variable language_">self</span>.rows = raw, <span class="hl-number">0</span>, []
    <span class="hl-keyword">def</span> <span class="hl-title function_">take</span>(<span class="hl-params">self, n, name</span>):
        v = <span class="hl-variable language_">self</span>.b[<span class="hl-variable language_">self</span>.p:<span class="hl-variable language_">self</span>.p + n]
        <span class="hl-variable language_">self</span>.rows.append((<span class="hl-variable language_">self</span>.p, n, name, v)); <span class="hl-variable language_">self</span>.p += n
        <span class="hl-keyword">return</span> v
    <span class="hl-keyword">def</span> <span class="hl-title function_">u32</span>(<span class="hl-params">self, name</span>): <span class="hl-keyword">return</span> struct.unpack(<span class="hl-string">&#x27;&lt;I&#x27;</span>, <span class="hl-variable language_">self</span>.take(<span class="hl-number">4</span>, name))[<span class="hl-number">0</span>]
    <span class="hl-keyword">def</span> <span class="hl-title function_">i64</span>(<span class="hl-params">self, name</span>): <span class="hl-keyword">return</span> struct.unpack(<span class="hl-string">&#x27;&lt;q&#x27;</span>, <span class="hl-variable language_">self</span>.take(<span class="hl-number">8</span>, name))[<span class="hl-number">0</span>]
    <span class="hl-keyword">def</span> <span class="hl-title function_">compact</span>(<span class="hl-params">self, name</span>):              <span class="hl-comment"># Bitcoin CompactSize</span>
        first = <span class="hl-variable language_">self</span>.b[<span class="hl-variable language_">self</span>.p]
        size = {<span class="hl-number">0xfd</span>: <span class="hl-number">3</span>, <span class="hl-number">0xfe</span>: <span class="hl-number">5</span>, <span class="hl-number">0xff</span>: <span class="hl-number">9</span>}.get(first, <span class="hl-number">1</span>)
        v = <span class="hl-variable language_">self</span>.take(size, name)
        <span class="hl-keyword">return</span> first <span class="hl-keyword">if</span> size == <span class="hl-number">1</span> <span class="hl-keyword">else</span> <span class="hl-built_in">int</span>.from_bytes(v[<span class="hl-number">1</span>:], <span class="hl-string">&#x27;little&#x27;</span>)

<span class="hl-keyword">def</span> <span class="hl-title function_">action_bundle</span>(<span class="hl-params">r, pool</span>):              <span class="hl-comment"># Orchard and Ironwood share this encoding</span>
    n = r.compact(<span class="hl-string">f&#x27;nActions<span class="hl-subst">{pool}</span>&#x27;</span>)
    <span class="hl-keyword">for</span> i <span class="hl-keyword">in</span> <span class="hl-built_in">range</span>(n):
        <span class="hl-keyword">for</span> field, size <span class="hl-keyword">in</span> [(<span class="hl-string">&#x27;cv&#x27;</span>, <span class="hl-number">32</span>), (<span class="hl-string">&#x27;nullifier&#x27;</span>, <span class="hl-number">32</span>), (<span class="hl-string">&#x27;rk&#x27;</span>, <span class="hl-number">32</span>), (<span class="hl-string">&#x27;cmx&#x27;</span>, <span class="hl-number">32</span>),
                            (<span class="hl-string">&#x27;ephemeralKey&#x27;</span>, <span class="hl-number">32</span>), (<span class="hl-string">&#x27;encCiphertext&#x27;</span>, <span class="hl-number">580</span>), (<span class="hl-string">&#x27;outCiphertext&#x27;</span>, <span class="hl-number">80</span>)]:
            r.take(size, <span class="hl-string">f&#x27;<span class="hl-subst">{pool}</span>.action[<span class="hl-subst">{i}</span>].<span class="hl-subst">{field}</span>&#x27;</span>)
    <span class="hl-keyword">if</span> n == <span class="hl-number">0</span>: <span class="hl-keyword">return</span> <span class="hl-number">0</span>, <span class="hl-number">0</span>
    r.take(<span class="hl-number">1</span>, <span class="hl-string">f&#x27;flags<span class="hl-subst">{pool}</span>&#x27;</span>)
    balance = r.i64(<span class="hl-string">f&#x27;valueBalance<span class="hl-subst">{pool}</span>&#x27;</span>)
    r.take(<span class="hl-number">32</span>, <span class="hl-string">f&#x27;anchor<span class="hl-subst">{pool}</span>&#x27;</span>)
    proof_len = r.compact(<span class="hl-string">f&#x27;sizeProofs<span class="hl-subst">{pool}</span>&#x27;</span>)
    <span class="hl-keyword">assert</span> proof_len == <span class="hl-number">2720</span> + <span class="hl-number">2272</span> * n, <span class="hl-string">&#x27;proof size rule (ZIP 229)&#x27;</span>
    r.take(proof_len, <span class="hl-string">f&#x27;proofs<span class="hl-subst">{pool}</span>&#x27;</span>)
    <span class="hl-keyword">for</span> i <span class="hl-keyword">in</span> <span class="hl-built_in">range</span>(n): r.take(<span class="hl-number">64</span>, <span class="hl-string">f&#x27;<span class="hl-subst">{pool}</span>.spendAuthSig[<span class="hl-subst">{i}</span>]&#x27;</span>)
    r.take(<span class="hl-number">64</span>, <span class="hl-string">f&#x27;bindingSig<span class="hl-subst">{pool}</span>&#x27;</span>)
    <span class="hl-keyword">return</span> n, balance

<span class="hl-keyword">def</span> <span class="hl-title function_">dissect</span>(<span class="hl-params">raw</span>):
    r = Reader(raw)
    header = r.u32(<span class="hl-string">&#x27;header&#x27;</span>)
    <span class="hl-keyword">assert</span> header &gt;&gt; <span class="hl-number">31</span> == <span class="hl-number">1</span> <span class="hl-keyword">and</span> header &amp; <span class="hl-number">0x7fffffff</span> == <span class="hl-number">6</span>, <span class="hl-string">&#x27;not a v6 transaction&#x27;</span>
    <span class="hl-keyword">assert</span> r.u32(<span class="hl-string">&#x27;nVersionGroupId&#x27;</span>) == <span class="hl-number">0xD884B698</span>
    branch = r.u32(<span class="hl-string">&#x27;nConsensusBranchId&#x27;</span>)
    r.u32(<span class="hl-string">&#x27;lock_time&#x27;</span>); expiry = r.u32(<span class="hl-string">&#x27;nExpiryHeight&#x27;</span>)
    t_in = r.compact(<span class="hl-string">&#x27;tx_in_count&#x27;</span>)
    <span class="hl-keyword">for</span> i <span class="hl-keyword">in</span> <span class="hl-built_in">range</span>(t_in):
        r.take(<span class="hl-number">36</span>, <span class="hl-string">f&#x27;tx_in[<span class="hl-subst">{i}</span>].prevout&#x27;</span>)
        r.take(r.compact(<span class="hl-string">f&#x27;tx_in[<span class="hl-subst">{i}</span>].script_len&#x27;</span>), <span class="hl-string">f&#x27;tx_in[<span class="hl-subst">{i}</span>].script&#x27;</span>)
        r.take(<span class="hl-number">4</span>, <span class="hl-string">f&#x27;tx_in[<span class="hl-subst">{i}</span>].sequence&#x27;</span>)
    t_out = r.compact(<span class="hl-string">&#x27;tx_out_count&#x27;</span>)
    <span class="hl-keyword">for</span> i <span class="hl-keyword">in</span> <span class="hl-built_in">range</span>(t_out):
        r.i64(<span class="hl-string">f&#x27;tx_out[<span class="hl-subst">{i}</span>].value&#x27;</span>)
        r.take(r.compact(<span class="hl-string">f&#x27;tx_out[<span class="hl-subst">{i}</span>].script_len&#x27;</span>), <span class="hl-string">f&#x27;tx_out[<span class="hl-subst">{i}</span>].script&#x27;</span>)
    s_sp = r.compact(<span class="hl-string">&#x27;nSpendsSapling&#x27;</span>); r.take(<span class="hl-number">96</span> * s_sp, <span class="hl-string">&#x27;vSpendsSapling&#x27;</span>)
    s_out = r.compact(<span class="hl-string">&#x27;nOutputsSapling&#x27;</span>); r.take(<span class="hl-number">756</span> * s_out, <span class="hl-string">&#x27;vOutputsSapling&#x27;</span>)
    sap_balance = r.i64(<span class="hl-string">&#x27;valueBalanceSapling&#x27;</span>) <span class="hl-keyword">if</span> s_sp + s_out <span class="hl-keyword">else</span> <span class="hl-number">0</span>
    <span class="hl-keyword">if</span> s_sp: r.take(<span class="hl-number">32</span>, <span class="hl-string">&#x27;anchorSapling&#x27;</span>)
    r.take(<span class="hl-number">192</span> * s_sp, <span class="hl-string">&#x27;vSpendProofsSapling&#x27;</span>); r.take(<span class="hl-number">64</span> * s_sp, <span class="hl-string">&#x27;vSpendAuthSigsSapling&#x27;</span>)
    r.take(<span class="hl-number">192</span> * s_out, <span class="hl-string">&#x27;vOutputProofsSapling&#x27;</span>)
    <span class="hl-keyword">if</span> s_sp + s_out: r.take(<span class="hl-number">64</span>, <span class="hl-string">&#x27;bindingSigSapling&#x27;</span>)
    orchard = action_bundle(r, <span class="hl-string">&#x27;Orchard&#x27;</span>)
    ironwood = action_bundle(r, <span class="hl-string">&#x27;Ironwood&#x27;</span>)
    <span class="hl-keyword">assert</span> r.p == <span class="hl-built_in">len</span>(raw), <span class="hl-string">&#x27;trailing bytes&#x27;</span>
    <span class="hl-built_in">print</span>(<span class="hl-string">f&#x27;v6 tx, <span class="hl-subst">{<span class="hl-built_in">len</span>(raw):,}</span> bytes, branch <span class="hl-subst">{branch:#<span class="hl-number">0</span>10x}</span>, expiry height <span class="hl-subst">{expiry:,}</span>&#x27;</span>)
    <span class="hl-built_in">print</span>(<span class="hl-string">f&#x27;transparent <span class="hl-subst">{t_in}</span> in / <span class="hl-subst">{t_out}</span> out · sapling <span class="hl-subst">{s_sp}</span> spends / <span class="hl-subst">{s_out}</span> outputs &#x27;</span>
          <span class="hl-string">f&#x27;· orchard <span class="hl-subst">{orchard[<span class="hl-number">0</span>]}</span> actions · ironwood <span class="hl-subst">{ironwood[<span class="hl-number">0</span>]}</span> actions&#x27;</span>)
    <span class="hl-built_in">print</span>(<span class="hl-string">f&#x27;value balances (zat): sapling <span class="hl-subst">{sap_balance:+,}</span> · orchard <span class="hl-subst">{orchard[<span class="hl-number">1</span>]:+,}</span> · ironwood <span class="hl-subst">{ironwood[<span class="hl-number">1</span>]:+,}</span>&#x27;</span>)
    <span class="hl-keyword">for</span> off, n, name, v <span class="hl-keyword">in</span> r.rows:
        <span class="hl-keyword">if</span> n == <span class="hl-number">0</span> <span class="hl-keyword">or</span> (<span class="hl-string">&#x27;.action[&#x27;</span> <span class="hl-keyword">in</span> name <span class="hl-keyword">and</span> <span class="hl-string">&#x27;.action[0].&#x27;</span> <span class="hl-keyword">not</span> <span class="hl-keyword">in</span> name): <span class="hl-keyword">continue</span>
        <span class="hl-built_in">print</span>(<span class="hl-string">f&#x27;<span class="hl-subst">{off:&gt;<span class="hl-number">6</span>}</span>  <span class="hl-subst">{n:&gt;<span class="hl-number">6</span>}</span>  <span class="hl-subst">{name:&lt;<span class="hl-number">28</span>}</span> <span class="hl-subst">{v[:<span class="hl-number">12</span>].<span class="hl-built_in">hex</span>()}</span><span class="hl-subst">{<span class="hl-string">&quot;…&quot;</span> <span class="hl-keyword">if</span> n &gt; <span class="hl-number">12</span> <span class="hl-keyword">else</span> <span class="hl-string">&quot;&quot;</span>}</span>&#x27;</span>)

<span class="hl-keyword">if</span> __name__ == <span class="hl-string">&#x27;__main__&#x27;</span>:
    dissect(<span class="hl-built_in">bytes</span>.fromhex(sys.argv[<span class="hl-number">1</span>]))</code></pre></div>
<p>Run it on our specimen and the first three lines should read:</p>
<div class="code-block" data-lang="text"><div class="code-head"><span class="code-lang">Output</span></div><pre><code class="language-text">v6 tx, 15,478 bytes, branch 0x37a5165b, expiry height 4,412,490
transparent 0 in / 0 out · sapling 0 spends / 0 outputs · orchard 0 actions · ironwood 4 actions
value balances (zat): sapling +0 · orchard +0 · ironwood +20,000</code></pre></div>
<p><strong>Exercises.</strong> Do these before Lecture 2; each one checks one of today&#39;s outcomes.</p>
<ol>
<li>Dissect the FROST batch, <code>878b44b81d518e5d5333f9d21e5f4d6017c6ce16afbdf484eb7a038b7edd355c</code>, and list every field that differs from the single-key specimen. Then explain why the list is so short.</li>
<li>Dissect the coinbase of testnet block 4,412,453, <code>d42ae723ce18124c5dc3fc33d30588c65f131ed4e663727acba6e2bdf6899e19</code>. Decode its two outputs and find where our specimen&#39;s fee went. Then find out what the second output is for (start with ZIP 207).</li>
<li>On your regtest chain, dissect the coinbase of block 1, then extend the script so it refuses a transaction whose branch ID is not one it recognises. Which upgrade&#39;s branch ID would you have to add for a chain past NU7?</li>
<li>Using the proof-size formula and ZIP 317, write a function that predicts the size and fee of a payout to N suppliers before you build it. Check it against the specimen. Keep it, because Lecture 5 needs it.</li>
</ol>
<h2 id="what-we-covered-and-where-we-go-next">What we covered, and where we go next</h2>
<p>Let&#39;s check off the outcomes.</p>
<p>You can now name the five components that replaced zcashd: Zebra and Zakura validate, the indexer turns blocks into compact blocks, Zallet replaces the zcashd wallet, and librustzcash is the library underneath all the wallets. You can trace a payment through eight steps and say which component owns each one. You can read a v6 header and see from its branch ID that our specimen was built for NU6.3. You know what each of the 820 bytes in an action is for, and that only the recipient&#39;s viewing key opens the 580 that matter to them. And you know how the chain keeps honest books per pool without seeing a single amount.</p>
<p>Here are the numbers worth keeping in your head from today:</p>
<div class="table-scroll" role="region" tabindex="0" aria-label="Table"><table>
<thead>
<tr>
<th>What</th>
<th>Value</th>
<th>Source</th>
</tr>
</thead>
<tbody><tr>
<td>Our specimen</td>
<td>15,478 bytes, 4 Ironwood actions, fee 20,000 zat</td>
<td>Testnet <code>de5d2562…</code>, dissected above</td>
</tr>
<tr>
<td>One Orchard-protocol action</td>
<td>820 bytes, of which 580 is the encrypted note with a 512-byte memo</td>
<td>ZIP 229</td>
</tr>
<tr>
<td>Proof size</td>
<td>2,720 + 2,272 × actions bytes</td>
<td>ZIP 229</td>
</tr>
<tr>
<td>Standard fee today</td>
<td>5,000 zat per logical action, minimum 2 actions</td>
<td>ZIP 317 (ZIP 2009 proposes 1,000)</td>
</tr>
<tr>
<td>Default expiry</td>
<td>40 blocks after the target height</td>
<td>librustzcash <code>DEFAULT_TX_EXPIRY_DELTA</code></td>
</tr>
<tr>
<td>NU6.3 (Ironwood)</td>
<td>Mainnet height 3,428,143, branch ID 0x37A5165B</td>
<td>ZIP 258</td>
</tr>
<tr>
<td>NU7</td>
<td>Mainnet height 3,543,405, branch ID 0x77190AD9, 25-second blocks</td>
<td>Zebra 7.0.0, ZIP 218</td>
</tr>
</tbody></table>
</div>
<p><strong>Next lecture: &quot;One viewing key, a million customers&quot;.</strong> We take step 8 of Fig 04, discovery, and price it. You will see why a shielded backend&#39;s cost grows with the number of keys it watches rather than the number of addresses it hands out, and we will design customer accounts around that fact, using Corridor&#39;s vault-per-customer model and sealForge&#39;s escrow-per-auction model as the two ends of the trade-off.</p>
<p>NOTE: Corridor&#39;s shielded lane and sealForge both run on Zcash testnet only. Neither has run on mainnet, and nothing here is financial advice. Ecosystem facts are as of 16 November 2026 and checked against the sources below; Zcash is moving quickly, so check the current ZIPs before you build on a detail.</p>
<p>If you work on any of these components, or you are building a Zcash backend and want to compare notes, I would like to hear from you, and both repositories are open to contributors.</p>
<h2 id="references">References</h2>
<ul>
<li><a href="https://zips.z.cash/zip-0229">ZIP 229: Version 6 Transaction Format</a></li>
<li><a href="https://zips.z.cash/zip-0258">ZIP 258: Deployment of the NU6.3 Network Upgrade</a></li>
<li><a href="https://zips.z.cash/zip-0257">ZIP 257: Deployment of the Orchard Temporary Vulnerability Mitigation and NU6.2</a></li>
<li><a href="https://zips.z.cash/zip-2005">ZIP 2005: Ironwood Quantum Recoverability</a></li>
<li><a href="https://zips.z.cash/zip-2006">ZIP 2006: Restricting Transfers into the Orchard Pool</a></li>
<li><a href="https://zips.z.cash/zip-0209">ZIP 209: Prohibit Out-of-Range Chain Value Pool Balances</a></li>
<li><a href="https://zips.z.cash/zip-0317">ZIP 317: Proportional Transfer Fee Mechanism</a> and <a href="https://github.com/zcash/zips/blob/main/zips/zip-2009.md">ZIP 2009</a> (proposed)</li>
<li><a href="https://github.com/zcash/zips/blob/main/zips/zip-0218.md">ZIP 218: 25-second Block Target Spacing</a></li>
<li><a href="https://zips.z.cash/zip-0225">ZIP 225: Version 5 Transaction Format</a></li>
<li><a href="https://forum.zcashcommunity.com/t/zebra-7-0-0-release/58442">Zebra 7.0.0 release</a> and <a href="https://github.com/ZcashFoundation/zebra/blob/main/zebra-chain/src/parameters/network_upgrade.rs">Zebra <code>network_upgrade.rs</code></a></li>
<li><a href="https://github.com/zakura-core/zakura">Zakura</a>, <a href="https://github.com/zcash/zallet">Zallet</a>, <a href="https://github.com/ZcashFoundation/z3">Z3</a>, <a href="https://github.com/zcash/lightwalletd">lightwalletd</a>, <a href="https://github.com/zingolabs/zaino">Zaino</a>, <a href="https://forum.zcashcommunity.com/t/announcing-zingod/58973">Announcing Zingod</a></li>
<li><a href="https://forum.zcashcommunity.com/t/fee-divergence-between-zebra-and-zakura-questions/58564">Fee divergence between Zebra and Zakura</a></li>
<li><a href="https://github.com/zcash/lightwallet-protocol/blob/main/walletrpc/compact_formats.proto">compact_formats.proto</a></li>
<li><a href="https://github.com/Udoka-AM/corridor/blob/main/apps/docs/integrations/zcash.mdx">Corridor: the Zcash shielded lane</a> and <a href="https://github.com/Udoka-AM/sealForge">sealForge</a></li>
</ul>
]]></content:encoded>
    </item>
    <item>
      <title>Maximising QuickNode for Solana development: an African developer's guide</title>
      <link>https://udokaam.dev/writing/maximising-quicknode-for-solana-development/</link>
      <guid isPermaLink="true">https://udokaam.dev/writing/maximising-quicknode-for-solana-development/</guid>
      <pubDate>Mon, 23 Sep 2024 00:00:00 GMT</pubDate>
      <dc:creator>Udoka A.M.</dc:creator>
      <category>infrastructure</category>
      <description>Building on Solana from a region where the connection drops: retries and failover against QuickNode's endpoints, WebSockets and the NFT API, and two dApps — remittance and agricultural supply chain — worked through in code.</description>
      <media:content url="https://udokaam.dev/writing/maximising-quicknode-for-solana-development/og.png" medium="image" />
      <content:encoded><![CDATA[<h2 id="1-introduction">1. Introduction</h2>
<p>As an African developer venturing into the world of Solana blockchain development, you&#39;re part of a growing community that&#39;s shaping the future of decentralised finance and applications on the continent. This guide will help you maximize the use of QuickNode, a powerful blockchain infrastructure provider, to overcome unique challenges and build innovative Solana applications tailored to African needs.</p>
<h2 id="2-understanding-quicknode-and-its-importance">2. Understanding QuickNode and Its Importance</h2>
<p>QuickNode provides high-performance blockchain infrastructure, offering developers reliable and fast access to blockchain networks, including Solana. For African developers, QuickNode can be a game-changer, providing:</p>
<ul>
<li>Reliable and fast access to the Solana network, crucial in regions with inconsistent internet connectivity.</li>
<li>Scalable infrastructure that can grow with your project, from a small startup to a continent-wide application.</li>
<li>Advanced features and APIs that can help build sophisticated applications addressing African-specific use cases.</li>
</ul>
<h2 id="3-setting-up-quicknode-for-solana">3. Setting Up QuickNode for Solana</h2>
<p>To get started with QuickNode for Solana development:</p>
<ol>
<li><p>Sign up for a QuickNode account at <a href="https://www.quicknode.com">https://www.quicknode.com</a>.</p>
</li>
<li><p>Create a new Solana endpoint:</p>
<ul>
<li>Choose Solana from the list of supported chains.</li>
<li>Select your preferred network (Mainnet, Testnet, or Devnet).</li>
<li>Choose a plan that fits your needs and budget.</li>
</ul>
</li>
<li><p>Once your endpoint is created, you&#39;ll receive an HTTP and WSS URL. Keep these secure, as you&#39;ll use them to connect your application to the Solana network.</p>
</li>
</ol>
<h2 id="4-overcoming-african-specific-challenges">4. Overcoming African-Specific Challenges</h2>
<p>African developers often face unique challenges. Here&#39;s how QuickNode can help address some of these:</p>
<ol>
<li><p><strong>Unreliable Internet Connectivity</strong>: 
QuickNode&#39;s globally distributed infrastructure can provide more stable connections compared to public nodes. Implement robust error handling and retry mechanisms in your code:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> { <span class="hl-title class_">Connection</span>, <span class="hl-title class_">PublicKey</span> } = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);
<span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeEndpoint</span> = <span class="hl-string">&#x27;YOUR_QUICKNODE_URL&#x27;</span>;

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getAccountInfo</span>(<span class="hl-params">publicKey</span>) {
  <span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> <span class="hl-title class_">Connection</span>(<span class="hl-title class_">QuickNodeEndpoint</span>);
  <span class="hl-keyword">const</span> maxRetries = <span class="hl-number">5</span>;
  <span class="hl-keyword">let</span> retries = <span class="hl-number">0</span>;

  <span class="hl-keyword">while</span> (retries &lt; maxRetries) {
    <span class="hl-keyword">try</span> {
      <span class="hl-keyword">const</span> accountInfo = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getAccountInfo</span>(<span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(publicKey));
      <span class="hl-keyword">return</span> accountInfo;
    } <span class="hl-keyword">catch</span> (error) {
      <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">`Attempt <span class="hl-subst">${retries + <span class="hl-number">1</span>}</span> failed. Retrying...`</span>);
      retries++;
      <span class="hl-keyword">if</span> (retries === maxRetries) {
        <span class="hl-keyword">throw</span> <span class="hl-keyword">new</span> <span class="hl-title class_">Error</span>(<span class="hl-string">&#x27;Max retries reached. Please check your internet connection.&#x27;</span>);
      }
      <span class="hl-comment">// Wait for 2 seconds before retrying</span>
      <span class="hl-keyword">await</span> <span class="hl-keyword">new</span> <span class="hl-title class_">Promise</span>(<span class="hl-function"><span class="hl-params">resolve</span> =&gt;</span> <span class="hl-built_in">setTimeout</span>(resolve, <span class="hl-number">2000</span>));
    }
  }
}</code></pre></div>
</li>
<li><p><strong>Limited Access to Developer Resources</strong>:
QuickNode provides extensive documentation and support. Utilise their learning resources and join developer communities for knowledge sharing.</p>
</li>
<li><p><strong>Power Outages</strong>:
Implement state management and data persistence in your applications to handle unexpected disconnections:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> fs = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;fs&#x27;</span>);

<span class="hl-keyword">function</span> <span class="hl-title function_">saveState</span>(<span class="hl-params">state</span>) {
  fs.<span class="hl-title function_">writeFileSync</span>(<span class="hl-string">&#x27;app_state.json&#x27;</span>, <span class="hl-title class_">JSON</span>.<span class="hl-title function_">stringify</span>(state));
}

<span class="hl-keyword">function</span> <span class="hl-title function_">loadState</span>(<span class="hl-params"></span>) {
  <span class="hl-keyword">if</span> (fs.<span class="hl-title function_">existsSync</span>(<span class="hl-string">&#x27;app_state.json&#x27;</span>)) {
    <span class="hl-keyword">return</span> <span class="hl-title class_">JSON</span>.<span class="hl-title function_">parse</span>(fs.<span class="hl-title function_">readFileSync</span>(<span class="hl-string">&#x27;app_state.json&#x27;</span>, <span class="hl-string">&#x27;utf8&#x27;</span>));
  }
  <span class="hl-keyword">return</span> <span class="hl-literal">null</span>;
}

<span class="hl-comment">// Use these functions in your app to save and recover state</span></code></pre></div>
</li>
<li><p><strong>Limited Hardware Resources</strong>:
Optimise your code for efficiency. Use QuickNode&#39;s powerful infrastructure to offload heavy computations:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-comment">// Instead of this (which may be heavy on local resources):</span>
<span class="hl-keyword">const</span> largeDataset = <span class="hl-keyword">await</span> <span class="hl-title function_">processLargeDataLocally</span>();

<span class="hl-comment">// Use QuickNode&#x27;s RPC to offload computation:</span>
<span class="hl-keyword">const</span> largeDataset = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getProgramAccounts</span>(
  <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(<span class="hl-string">&#x27;YourProgramId&#x27;</span>),
  {
    <span class="hl-attr">filters</span>: [
      {
        <span class="hl-attr">dataSize</span>: <span class="hl-number">100</span> <span class="hl-comment">// Example filter</span>
      },
      {
        <span class="hl-attr">memcmp</span>: {
          <span class="hl-attr">offset</span>: <span class="hl-number">4</span>,
          <span class="hl-attr">bytes</span>: <span class="hl-string">&#x27;base58 encoded string&#x27;</span>
        }
      }
    ]
  }
);</code></pre></div>
</li>
</ol>
<h2 id="5-maximising-quicknode-features">5. Maximising QuickNode Features</h2>
<h3 id="51-high-performance-rpc-endpoints">5.1 High-Performance RPC Endpoints</h3>
<p>QuickNode&#39;s RPC endpoints offer superior performance. Here&#39;s how to make the most of them:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> { <span class="hl-title class_">Connection</span>, <span class="hl-title class_">PublicKey</span> } = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);

<span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeEndpoint</span> = <span class="hl-string">&#x27;YOUR_QUICKNODE_URL&#x27;</span>;
<span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> <span class="hl-title class_">Connection</span>(<span class="hl-title class_">QuickNodeEndpoint</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getBalance</span>(<span class="hl-params">address</span>) {
  <span class="hl-keyword">const</span> publicKey = <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(address);
  <span class="hl-keyword">const</span> balance = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getBalance</span>(publicKey);
  <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">`Balance: <span class="hl-subst">${balance / <span class="hl-number">10</span>**<span class="hl-number">9</span>}</span> SOL`</span>);
}

<span class="hl-comment">// Example usage</span>
<span class="hl-title function_">getBalance</span>(<span class="hl-string">&#x27;AfzGtGEUkZtYq1s4xbgcteJ5bvLNsTeRJtE9qXzjUWW6&#x27;</span>);</code></pre></div>
<h3 id="52-add-ons-and-analytics">5.2 Add-ons and Analytics</h3>
<p>Leverage QuickNode&#39;s add-ons for enhanced functionality:</p>
<ol>
<li><strong>Trace API</strong>: Useful for debugging transactions, especially in complex DeFi applications.</li>
</ol>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> traceResponse = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">sendRawTransaction</span>(
  rawTransaction,
  { <span class="hl-attr">maxRetries</span>: <span class="hl-number">5</span>, <span class="hl-attr">skipPreflight</span>: <span class="hl-literal">true</span>, <span class="hl-attr">preflightCommitment</span>: <span class="hl-string">&#x27;confirmed&#x27;</span> },
  { <span class="hl-attr">trace</span>: <span class="hl-literal">true</span> }
);
<span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Transaction Trace:&#x27;</span>, traceResponse);</code></pre></div>
<ol start="2">
<li><strong>Analytics</strong>: Monitor your dApp&#39;s performance and usage patterns.</li>
</ol>
<p>Access analytics data through the QuickNode dashboard to optimise your application based on usage patterns specific to your African user base.</p>
<h3 id="53-websockets-for-real-time-data">5.3 WebSockets for Real-Time Data</h3>
<p>Implement WebSockets for real-time updates, crucial for applications like remittance services or market data:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> { <span class="hl-title class_">Connection</span>, <span class="hl-title class_">PublicKey</span> } = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);

<span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeWSSEndpoint</span> = <span class="hl-string">&#x27;YOUR_QUICKNODE_WSS_URL&#x27;</span>;
<span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> <span class="hl-title class_">Connection</span>(<span class="hl-title class_">QuickNodeWSSEndpoint</span>);

<span class="hl-keyword">const</span> programId = <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(<span class="hl-string">&#x27;YOUR_PROGRAM_ID&#x27;</span>);

connection.<span class="hl-title function_">onProgramAccountChange</span>(
  programId,
  <span class="hl-function">(<span class="hl-params">accountInfo, context</span>) =&gt;</span> {
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Account changed:&#x27;</span>, accountInfo.<span class="hl-property">accountId</span>.<span class="hl-title function_">toBase58</span>());
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;New account data:&#x27;</span>, accountInfo.<span class="hl-property">accountInfo</span>.<span class="hl-property">data</span>);
  },
  <span class="hl-string">&#x27;confirmed&#x27;</span>
);</code></pre></div>
<h3 id="54-nft-api-integration">5.4 NFT API Integration</h3>
<p>For projects involving digital art or tokenised assets (e.g., representing ownership of physical goods), use QuickNode&#39;s NFT API:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> axios = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;axios&#x27;</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getNFTMetadata</span>(<span class="hl-params">mintAddress</span>) {
  <span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeNFTAPI</span> = <span class="hl-string">&#x27;https://YOUR_QUICKNODE_ENDPOINT/nft/v1/solana/nft/&#x27;</span>;
  
  <span class="hl-keyword">try</span> {
    <span class="hl-keyword">const</span> response = <span class="hl-keyword">await</span> axios.<span class="hl-title function_">get</span>(<span class="hl-string">`<span class="hl-subst">${QuickNodeNFTAPI}</span><span class="hl-subst">${mintAddress}</span>`</span>);
    <span class="hl-keyword">return</span> response.<span class="hl-property">data</span>;
  } <span class="hl-keyword">catch</span> (error) {
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">error</span>(<span class="hl-string">&#x27;Error fetching NFT metadata:&#x27;</span>, error);
  }
}

<span class="hl-comment">// Example usage</span>
<span class="hl-title function_">getNFTMetadata</span>(<span class="hl-string">&#x27;MINT_ADDRESS&#x27;</span>).<span class="hl-title function_">then</span>(<span class="hl-function"><span class="hl-params">metadata</span> =&gt;</span> <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(metadata));</code></pre></div>
<h2 id="6-building-african-centric-solana-dapps-with-quicknode">6. Building African-Centric Solana dApps with QuickNode</h2>
<p>Let&#39;s explore how to build Solana dApps that address African needs using QuickNode:</p>
<h3 id="61-remittance-dapp">6.1 Remittance dApp</h3>
<p>Create a remittance service that leverages Solana&#39;s fast and low-cost transactions:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> { <span class="hl-title class_">Connection</span>, <span class="hl-title class_">PublicKey</span>, <span class="hl-title class_">Transaction</span>, <span class="hl-title class_">SystemProgram</span> } = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);

<span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeEndpoint</span> = <span class="hl-string">&#x27;YOUR_QUICKNODE_URL&#x27;</span>;
<span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> <span class="hl-title class_">Connection</span>(<span class="hl-title class_">QuickNodeEndpoint</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">sendRemittance</span>(<span class="hl-params">senderKeypair, recipientAddress, amount</span>) {
  <span class="hl-keyword">const</span> transaction = <span class="hl-keyword">new</span> <span class="hl-title class_">Transaction</span>().<span class="hl-title function_">add</span>(
    <span class="hl-title class_">SystemProgram</span>.<span class="hl-title function_">transfer</span>({
      <span class="hl-attr">fromPubkey</span>: senderKeypair.<span class="hl-property">publicKey</span>,
      <span class="hl-attr">toPubkey</span>: <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(recipientAddress),
      <span class="hl-attr">lamports</span>: amount * <span class="hl-number">10</span>**<span class="hl-number">9</span> <span class="hl-comment">// Convert SOL to lamports</span>
    })
  );

  <span class="hl-keyword">const</span> signature = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">sendTransaction</span>(transaction, [senderKeypair]);
  <span class="hl-keyword">await</span> connection.<span class="hl-title function_">confirmTransaction</span>(signature);

  <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Remittance sent successfully:&#x27;</span>, signature);
}</code></pre></div>
<h3 id="62-agricultural-supply-chain-tracking">6.2 Agricultural Supply Chain Tracking</h3>
<p>Develop a dApp to track agricultural products from farm to market:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> { <span class="hl-title class_">Connection</span>, <span class="hl-title class_">PublicKey</span>, <span class="hl-title class_">Transaction</span> } = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);
<span class="hl-keyword">const</span> <span class="hl-title class_">BufferLayout</span> = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;buffer-layout&#x27;</span>);

<span class="hl-keyword">const</span> <span class="hl-title class_">QuickNodeEndpoint</span> = <span class="hl-string">&#x27;YOUR_QUICKNODE_URL&#x27;</span>;
<span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> <span class="hl-title class_">Connection</span>(<span class="hl-title class_">QuickNodeEndpoint</span>);

<span class="hl-keyword">const</span> <span class="hl-variable constant_">PRODUCT_ACCOUNT_DATA_LAYOUT</span> = <span class="hl-title class_">BufferLayout</span>.<span class="hl-title function_">struct</span>([
  <span class="hl-title class_">BufferLayout</span>.<span class="hl-title function_">u8</span>(<span class="hl-string">&#x27;isInitialized&#x27;</span>),
  <span class="hl-title class_">BufferLayout</span>.<span class="hl-title function_">blob</span>(<span class="hl-number">32</span>, <span class="hl-string">&#x27;productId&#x27;</span>),
  <span class="hl-title class_">BufferLayout</span>.<span class="hl-title function_">u8</span>(<span class="hl-string">&#x27;stage&#x27;</span>), <span class="hl-comment">// 0: Farm, 1: Processing, 2: Distribution, 3: Retail</span>
  <span class="hl-title class_">BufferLayout</span>.<span class="hl-title function_">blob</span>(<span class="hl-number">64</span>, <span class="hl-string">&#x27;metadata&#x27;</span>)
]);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">updateProductStage</span>(<span class="hl-params">productAccount, newStage, updateAuthority</span>) {
  <span class="hl-keyword">const</span> productInfo = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getAccountInfo</span>(<span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(productAccount));
  <span class="hl-keyword">const</span> productData = <span class="hl-variable constant_">PRODUCT_ACCOUNT_DATA_LAYOUT</span>.<span class="hl-title function_">decode</span>(productInfo.<span class="hl-property">data</span>);

  productData.<span class="hl-property">stage</span> = newStage;

  <span class="hl-keyword">const</span> instruction = <span class="hl-keyword">new</span> <span class="hl-title class_">Transaction</span>().<span class="hl-title function_">add</span>({
    <span class="hl-attr">keys</span>: [{ <span class="hl-attr">pubkey</span>: <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(productAccount), <span class="hl-attr">isSigner</span>: <span class="hl-literal">false</span>, <span class="hl-attr">isWritable</span>: <span class="hl-literal">true</span> }],
    <span class="hl-attr">programId</span>: <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(<span class="hl-string">&#x27;YOUR_PROGRAM_ID&#x27;</span>),
    <span class="hl-attr">data</span>: <span class="hl-title class_">Buffer</span>.<span class="hl-title function_">from</span>([...<span class="hl-variable constant_">PRODUCT_ACCOUNT_DATA_LAYOUT</span>.<span class="hl-title function_">encode</span>(productData)])
  });

  <span class="hl-keyword">const</span> signature = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">sendTransaction</span>(instruction, [updateAuthority]);
  <span class="hl-keyword">await</span> connection.<span class="hl-title function_">confirmTransaction</span>(signature);

  <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Product stage updated successfully:&#x27;</span>, signature);
}</code></pre></div>
<h2 id="7-best-practices-and-optimization-tips">7. Best Practices and Optimization Tips</h2>
<ol>
<li><p><strong>Implement Caching</strong>: 
Cache frequently accessed data to reduce RPC calls and improve performance:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> <span class="hl-title class_">NodeCache</span> = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;node-cache&#x27;</span>);
<span class="hl-keyword">const</span> cache = <span class="hl-keyword">new</span> <span class="hl-title class_">NodeCache</span>({ <span class="hl-attr">stdTTL</span>: <span class="hl-number">600</span> }); <span class="hl-comment">// Cache for 10 minutes</span>

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getCachedAccountInfo</span>(<span class="hl-params">publicKey</span>) {
  <span class="hl-keyword">const</span> cacheKey = <span class="hl-string">`accountInfo_<span class="hl-subst">${publicKey}</span>`</span>;
  <span class="hl-keyword">let</span> accountInfo = cache.<span class="hl-title function_">get</span>(cacheKey);

  <span class="hl-keyword">if</span> (!accountInfo) {
    accountInfo = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getAccountInfo</span>(<span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(publicKey));
    cache.<span class="hl-title function_">set</span>(cacheKey, accountInfo);
  }

  <span class="hl-keyword">return</span> accountInfo;
}</code></pre></div>
</li>
<li><p><strong>Batch Requests</strong>: 
Group multiple RPC requests to reduce network overhead:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> publicKeys = [
  <span class="hl-string">&#x27;PublicKey1&#x27;</span>,
  <span class="hl-string">&#x27;PublicKey2&#x27;</span>,
  <span class="hl-string">&#x27;PublicKey3&#x27;</span>
].<span class="hl-title function_">map</span>(<span class="hl-function"><span class="hl-params">key</span> =&gt;</span> <span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(key));

<span class="hl-keyword">const</span> accountInfos = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getMultipleAccountsInfo</span>(publicKeys);</code></pre></div>
</li>
<li><p><strong>Error Handling and Logging</strong>:
Implement robust error handling and logging for better debugging, especially important in environments with unstable internet:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> winston = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;winston&#x27;</span>);
<span class="hl-keyword">const</span> logger = winston.<span class="hl-title function_">createLogger</span>({
  <span class="hl-attr">level</span>: <span class="hl-string">&#x27;info&#x27;</span>,
  <span class="hl-attr">format</span>: winston.<span class="hl-property">format</span>.<span class="hl-title function_">json</span>(),
  <span class="hl-attr">transports</span>: [
    <span class="hl-keyword">new</span> winston.<span class="hl-property">transports</span>.<span class="hl-title class_">File</span>({ <span class="hl-attr">filename</span>: <span class="hl-string">&#x27;error.log&#x27;</span>, <span class="hl-attr">level</span>: <span class="hl-string">&#x27;error&#x27;</span> }),
    <span class="hl-keyword">new</span> winston.<span class="hl-property">transports</span>.<span class="hl-title class_">File</span>({ <span class="hl-attr">filename</span>: <span class="hl-string">&#x27;combined.log&#x27;</span> })
  ]
});

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">safeGetBalance</span>(<span class="hl-params">address</span>) {
  <span class="hl-keyword">try</span> {
    <span class="hl-keyword">const</span> balance = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getBalance</span>(<span class="hl-keyword">new</span> <span class="hl-title class_">PublicKey</span>(address));
    <span class="hl-keyword">return</span> balance;
  } <span class="hl-keyword">catch</span> (error) {
    logger.<span class="hl-title function_">error</span>(<span class="hl-string">&#x27;Error fetching balance&#x27;</span>, { address, <span class="hl-attr">error</span>: error.<span class="hl-property">message</span> });
    <span class="hl-keyword">throw</span> error;
  }
}</code></pre></div>
</li>
<li><p><strong>Optimize for Mobile</strong>: 
Given the prevalence of mobile internet in Africa, optimise your dApps for mobile devices:</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-comment">// Use responsive design in your frontend</span>
<span class="hl-comment">//Minimise data transfer</span>
<span class="hl-comment">// Implement offline capabilities where possible</span></code></pre></div>
</li>
<li><p><strong>Regular Monitoring</strong>:
Utilise QuickNode&#39;s monitoring tools to keep track of your application&#39;s performance and resource usage.</p>
</li>
</ol>
<h2 id="8-conclusion">8. Conclusion</h2>
<p>By leveraging the powerful infrastructure Quicknode offers and following these best practices, African developers can build robust, efficient, and scalable Solana applications that address unique continental challenges. From improving financial inclusion through remittance dApps to enhancing agricultural supply chains, the possibilities are vast.</p>
<p>Remember to stay engaged with both the African and global Solana developer communities. Share your experiences, contribute to open-source projects, and continue pushing the boundaries of what&#39;s possible with blockchain technology in Africa.</p>
<p>As you embark on your Solana development journey with QuickNode, you&#39;re not just building applications; you&#39;re helping to shape the future of blockchain technology in Africa. Embrace the challenges, leverage the tools at your disposal, and create solutions that will drive the continent forward in the decentralized era.</p>
]]></content:encoded>
    </item>
    <item>
      <title>Maximizing Helius for Solana development</title>
      <link>https://udokaam.dev/writing/maximizing-helius-for-solana-development/</link>
      <guid isPermaLink="true">https://udokaam.dev/writing/maximizing-helius-for-solana-development/</guid>
      <pubDate>Fri, 20 Sep 2024 00:00:00 GMT</pubDate>
      <dc:creator>Udoka A.M.</dc:creator>
      <category>infrastructure</category>
      <description>A working tour of Helius for Solana developers: RPC nodes, enhanced APIs, webhooks and the DAS API, with the code for each and the practices that keep them cheap.</description>
      <media:content url="https://udokaam.dev/writing/maximizing-helius-for-solana-development/og.png" medium="image" />
      <content:encoded><![CDATA[<h2 id="introduction-to-helius">Introduction to Helius</h2>
<p>I&#39;m not the best solana developer out there, but I have been around the block for a while now, picked up a few experiences and learnt a few things about the various technologies in the field. One of those really well distinguished tech is Helius, and I&#39;ll be sharing some things I have learned about it and how it can help your development journey on solana. </p>
<p>As the Solana ecosystem continues to grow and evolve, developers face increasing challenges in building scalable, efficient, and feature-rich applications. To mitigate these challenges, Helius, a powerful suite of tools and services is designed to enhance Solana development and unlock new possibilities for decentralized applications (dApps). In this comprehensive guide, we&#39;ll explore how to maximize Helius for your Solana development projects, diving deep into its features, use cases, and best practices.</p>
<h2 id="what-is-helius">What is Helius?</h2>
<p>Helius is a cutting-edge infrastructure provider for the Solana blockchain, offering a range of products and services that cater to the needs of developers, from hobbyists to enterprise-level teams. At its core, Helius provides enhanced RPC nodes, APIs, and tools that simplify the process of building, scaling, and maintaining Solana applications.</p>
<p>The platform stands out for its focus on performance, reliability, and developer experience. By leveraging Helius, developers can access high-performance RPC nodes, benefit from enriched transaction data, and utilize specialized APIs that abstract away much of the complexity involved in Solana development.</p>
<h2 id="why-helius-was-built">Why Helius Was Built</h2>
<p>Helius was created to address several pain points in the Solana development ecosystem:</p>
<ol>
<li><p><strong>Scalability Challenges</strong>: As Solana&#39;s popularity grew, many developers struggled with the limitations of public RPC nodes, which often became overwhelmed during periods of high network activity.</p>
</li>
<li><p><strong>Data Accessibility</strong>: Extracting meaningful data from raw Solana transactions was a time-consuming and complex process, hindering rapid development and innovation.</p>
</li>
<li><p><strong>Real-time Updates</strong>: There was a lack of efficient solutions for receiving real-time updates about on-chain events, crucial for many dApp use cases.</p>
</li>
<li><p><strong>NFT Ecosystem Complexity</strong>: The booming Solana NFT ecosystem introduced unique challenges in terms of metadata handling and real-time updates.</p>
</li>
<li><p><strong>Developer Experience</strong>: There was a need for more developer-friendly tools and APIs to lower the barrier to entry for Solana development.</p>
</li>
</ol>
<p>By addressing these challenges, Helius aims to accelerate the growth of the Solana ecosystem and empower developers to build more sophisticated and scalable applications.</p>
<h2 id="helius-products-and-use-cases">Helius Products and Use Cases</h2>
<h3 id="1-rpc-nodes">1. RPC Nodes</h3>
<p>Helius provides high-performance RPC nodes that offer superior speed and reliability compared to public nodes. These nodes are crucial for any Solana application, as they serve as the primary interface between your dApp and the Solana blockchain.</p>
<p><strong>Use Case</strong>: Building a high-frequency trading bot</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> web3 = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;@solana/web3.js&#x27;</span>);

<span class="hl-comment">// Connect to Helius RPC node</span>
<span class="hl-keyword">const</span> connection = <span class="hl-keyword">new</span> web3.<span class="hl-title class_">Connection</span>(<span class="hl-string">&#x27;https://rpc.helius.xyz/?api-key=YOUR_API_KEY&#x27;</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getLatestBlockhash</span>(<span class="hl-params"></span>) {
  <span class="hl-keyword">const</span> { blockhash, lastValidBlockHeight } = <span class="hl-keyword">await</span> connection.<span class="hl-title function_">getLatestBlockhash</span>();
  <span class="hl-keyword">return</span> { blockhash, lastValidBlockHeight };
}

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">sendTransaction</span>(<span class="hl-params">transaction</span>) {
  <span class="hl-keyword">const</span> { blockhash, lastValidBlockHeight } = <span class="hl-keyword">await</span> <span class="hl-title function_">getLatestBlockhash</span>();
  transaction.<span class="hl-property">recentBlockhash</span> = blockhash;
  
  <span class="hl-comment">// Sign and send the transaction</span>
  <span class="hl-keyword">const</span> signature = <span class="hl-keyword">await</span> web3.<span class="hl-title function_">sendAndConfirmTransaction</span>(connection, transaction, [payer]);
  <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Transaction sent:&#x27;</span>, signature);
}

<span class="hl-comment">// Use this function to send high-frequency trades</span></code></pre></div>
<h3 id="2-enhanced-apis">2. Enhanced APIs</h3>
<p>Helius offers enhanced APIs that provide enriched transaction data, making it easier to extract meaningful information from on-chain activities.</p>
<p><strong>Use Case</strong>: Tracking specific program interactions</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> axios = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;axios&#x27;</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getEnhancedTransactions</span>(<span class="hl-params">address</span>) {
  <span class="hl-keyword">const</span> url = <span class="hl-string">`https://api.helius.xyz/v0/addresses/<span class="hl-subst">${address}</span>/transactions?api-key=YOUR_API_KEY`</span>;
  <span class="hl-keyword">const</span> response = <span class="hl-keyword">await</span> axios.<span class="hl-title function_">get</span>(url);
  <span class="hl-keyword">return</span> response.<span class="hl-property">data</span>;
}

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">filterProgramInteractions</span>(<span class="hl-params">address, programId</span>) {
  <span class="hl-keyword">const</span> transactions = <span class="hl-keyword">await</span> <span class="hl-title function_">getEnhancedTransactions</span>(address);
  <span class="hl-keyword">return</span> transactions.<span class="hl-title function_">filter</span>(<span class="hl-function"><span class="hl-params">tx</span> =&gt;</span> 
    tx.<span class="hl-property">tokenTransfers</span>.<span class="hl-title function_">some</span>(<span class="hl-function"><span class="hl-params">transfer</span> =&gt;</span> transfer.<span class="hl-property">programId</span> === programId)
  );
}

<span class="hl-comment">// Usage</span>
<span class="hl-keyword">const</span> userAddress = <span class="hl-string">&#x27;USER_WALLET_ADDRESS&#x27;</span>;
<span class="hl-keyword">const</span> programId = <span class="hl-string">&#x27;PROGRAM_ID_TO_TRACK&#x27;</span>;
<span class="hl-title function_">filterProgramInteractions</span>(userAddress, programId)
  .<span class="hl-title function_">then</span>(<span class="hl-function"><span class="hl-params">interactions</span> =&gt;</span> <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Program interactions:&#x27;</span>, interactions));</code></pre></div>
<h3 id="3-webhooks">3. Webhooks</h3>
<p>Helius Webhooks allow developers to receive real-time notifications about on-chain events, enabling responsive and event-driven applications.</p>
<p><strong>Use Case</strong>: Real-time NFT sales tracker</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> express = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;express&#x27;</span>);
<span class="hl-keyword">const</span> app = <span class="hl-title function_">express</span>();
app.<span class="hl-title function_">use</span>(express.<span class="hl-title function_">json</span>());

app.<span class="hl-title function_">post</span>(<span class="hl-string">&#x27;/webhook&#x27;</span>, <span class="hl-function">(<span class="hl-params">req, res</span>) =&gt;</span> {
  <span class="hl-keyword">const</span> event = req.<span class="hl-property">body</span>;
  <span class="hl-keyword">if</span> (event.<span class="hl-property">type</span> === <span class="hl-string">&#x27;NFT_SALE&#x27;</span>) {
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;NFT Sale detected!&#x27;</span>);
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Seller:&#x27;</span>, event.<span class="hl-property">seller</span>);
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Buyer:&#x27;</span>, event.<span class="hl-property">buyer</span>);
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Price:&#x27;</span>, event.<span class="hl-property">price</span>);
    <span class="hl-comment">// Trigger your application logic here</span>
  }
  res.<span class="hl-title function_">sendStatus</span>(<span class="hl-number">200</span>);
});

<span class="hl-keyword">const</span> <span class="hl-variable constant_">PORT</span> = <span class="hl-number">3000</span>;
app.<span class="hl-title function_">listen</span>(<span class="hl-variable constant_">PORT</span>, <span class="hl-function">() =&gt;</span> <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">`Webhook server running on port <span class="hl-subst">${PORT}</span>`</span>));</code></pre></div>
<h3 id="4-nft-apis">4. NFT APIs</h3>
<p>Helius provides specialized APIs for working with NFTs on Solana, simplifying tasks like fetching metadata and tracking NFT activities.</p>
<p><strong>Use Case</strong>: Building an NFT gallery</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> axios = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;axios&#x27;</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">getNFTMetadata</span>(<span class="hl-params">mintAddresses</span>) {
  <span class="hl-keyword">const</span> url = <span class="hl-string">&#x27;https://api.helius.xyz/v0/tokens/metadata?api-key=YOUR_API_KEY&#x27;</span>;
  <span class="hl-keyword">const</span> response = <span class="hl-keyword">await</span> axios.<span class="hl-title function_">post</span>(url, { <span class="hl-attr">mintAccounts</span>: mintAddresses });
  <span class="hl-keyword">return</span> response.<span class="hl-property">data</span>;
}

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">displayNFTGallery</span>(<span class="hl-params">walletAddress</span>) {
  <span class="hl-keyword">const</span> url = <span class="hl-string">`https://api.helius.xyz/v0/addresses/<span class="hl-subst">${walletAddress}</span>/nfts?api-key=YOUR_API_KEY`</span>;
  <span class="hl-keyword">const</span> response = <span class="hl-keyword">await</span> axios.<span class="hl-title function_">get</span>(url);
  <span class="hl-keyword">const</span> nfts = response.<span class="hl-property">data</span>;
  
  <span class="hl-keyword">const</span> mintAddresses = nfts.<span class="hl-title function_">map</span>(<span class="hl-function"><span class="hl-params">nft</span> =&gt;</span> nft.<span class="hl-property">mintAddress</span>);
  <span class="hl-keyword">const</span> metadata = <span class="hl-keyword">await</span> <span class="hl-title function_">getNFTMetadata</span>(mintAddresses);
  
  metadata.<span class="hl-title function_">forEach</span>(<span class="hl-function"><span class="hl-params">nft</span> =&gt;</span> {
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Name:&#x27;</span>, nft.<span class="hl-property">onChainMetadata</span>.<span class="hl-property">metadata</span>.<span class="hl-property">data</span>.<span class="hl-property">name</span>);
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Image:&#x27;</span>, nft.<span class="hl-property">offChainMetadata</span>.<span class="hl-property">image</span>);
    <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;---&#x27;</span>);
  });
}

<span class="hl-comment">// Usage</span>
<span class="hl-title function_">displayNFTGallery</span>(<span class="hl-string">&#x27;USER_WALLET_ADDRESS&#x27;</span>);</code></pre></div>
<h3 id="5-das-api">5. DAS API</h3>
<p>The Digital Asset Standard (DAS) API provides a unified interface for querying NFT data across multiple Solana programs, making it easier to work with NFTs regardless of their underlying standard.</p>
<p><strong>Use Case</strong>: Cross-program NFT search</p>
<div class="code-block" data-lang="javascript"><div class="code-head"><span class="code-lang">JavaScript</span></div><pre><code class="language-javascript"><span class="hl-keyword">const</span> axios = <span class="hl-built_in">require</span>(<span class="hl-string">&#x27;axios&#x27;</span>);

<span class="hl-keyword">async</span> <span class="hl-keyword">function</span> <span class="hl-title function_">searchNFTs</span>(<span class="hl-params">query</span>) {
  <span class="hl-keyword">const</span> url = <span class="hl-string">&#x27;https://api.helius.xyz/v0/token-metadata?api-key=YOUR_API_KEY&#x27;</span>;
  <span class="hl-keyword">const</span> response = <span class="hl-keyword">await</span> axios.<span class="hl-title function_">post</span>(url, {
    <span class="hl-attr">query</span>: {
      <span class="hl-attr">firstVerifiedCreators</span>: [query]
    }
  });
  <span class="hl-keyword">return</span> response.<span class="hl-property">data</span>;
}

<span class="hl-comment">// Usage</span>
<span class="hl-title function_">searchNFTs</span>(<span class="hl-string">&#x27;CREATOR_ADDRESS&#x27;</span>)
  .<span class="hl-title function_">then</span>(<span class="hl-function"><span class="hl-params">nfts</span> =&gt;</span> <span class="hl-variable language_">console</span>.<span class="hl-title function_">log</span>(<span class="hl-string">&#x27;Found NFTs:&#x27;</span>, nfts));</code></pre></div>
<h2 id="maximizing-helius-in-your-solana-development">Maximizing Helius in Your Solana Development</h2>
<p>To get the most out of Helius in your Solana development:</p>
<ol>
<li><p><strong>Leverage Enhanced RPC Nodes</strong>: Replace public RPC endpoints with Helius nodes for improved performance and reliability.</p>
</li>
<li><p><strong>Utilize Enhanced Transaction Data</strong>: Take advantage of the enriched transaction data to simplify your application logic and reduce the need for complex on-chain data processing.</p>
</li>
<li><p><strong>Implement Webhooks</strong>: Use Helius Webhooks to create responsive, event-driven applications that react to on-chain events in real-time.</p>
</li>
<li><p><strong>Optimize NFT Handling</strong>: Leverage the NFT and DAS APIs to streamline NFT-related operations in your applications.</p>
</li>
<li><p><strong>Combine Multiple Helius Products</strong>: Integrate multiple Helius products to create powerful, feature-rich applications.</p>
</li>
</ol>
<h2 id="best-practices-and-tips">Best Practices and Tips</h2>
<ol>
<li><p><strong>API Key Management</strong>: Securely store and manage your Helius API keys. Never expose them in client-side code.</p>
</li>
<li><p><strong>Rate Limiting</strong>: Be aware of rate limits for different Helius products and implement appropriate throttling in your applications.</p>
</li>
<li><p><strong>Error Handling</strong>: Implement robust error handling to manage potential API downtime or rate limiting issues.</p>
</li>
<li><p><strong>Caching</strong>: Implement caching strategies to reduce unnecessary API calls and improve your application&#39;s performance.</p>
</li>
<li><p><strong>Webhook Security</strong>: When using webhooks, implement proper security measures such as signature verification to ensure the integrity of received data.</p>
</li>
<li><p><strong>Stay Updated</strong>: Keep an eye on Helius documentation and updates to take advantage of new features and improvements.</p>
</li>
<li><p><strong>Community Engagement</strong>: Participate in the Helius community to share knowledge, get support, and stay informed about best practices.</p>
</li>
</ol>
<h2 id="conclusion">Conclusion</h2>
<p>Helius provides a powerful suite of tools and services that can significantly enhance your Solana development experience. By leveraging its high-performance RPC nodes, enriched APIs, real-time webhooks, and specialized NFT tools, you can build more sophisticated, scalable, and responsive Solana applications.</p>
<p>As you integrate Helius into your development workflow, remember to follow best practices, stay updated with the latest features, and engage with the community. With Helius, you&#39;re not just accessing a set of tools, but tapping into an ecosystem designed to propel Solana development forward.</p>
<p>Whether you&#39;re building a DeFi application, an NFT marketplace, or exploring novel use cases on Solana, Helius provides the infrastructure and tools to turn your vision into reality. By maximizing the use of Helius in your projects, you&#39;re setting yourself up for success in the dynamic and exciting world of Solana development.</p>
]]></content:encoded>
    </item>
  </channel>
</rss>
