:orphan:

Examples
========

This gallery walks through ``blockchainkit.channels``, one experiment per
breakthrough on the :doc:`channels history page
</history/channels_breakthroughs>`: Reed-Solomon codes and data-availability
sampling; payment channels from Spilman's to Lightning, Sprites and eltoo,
with watchtowers; balance probing in a channel network; atomic swaps, BTC
Relay and the bridge exploits; and Plasma, sharding, and zk and optimistic
rollups.

Each script is self-contained and runs with
``python examples/channels/<section>/<script>.py``.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Erasure codes and data availability
-----------------------------------

Data as the values of a polynomial: recovering what was lost, and catching a block producer who hides part of a block.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Reed and Solomon treated k symbols of data as a polynomial of degree below k over a finite field, and sent its values at n points. Two such polynomials agree on at most k - 1 points, so any k of the n values determine all the others. The code survives the loss of up to n - k symbols, and up to (n - k) / 2 symbols that arrive wrong:">

.. only:: html

  .. image:: /api/gallery/channels/coding/images/thumb/sphx_glr_plot_01_reed_solomon_thumb.png
    :alt:

  :doc:`/api/gallery/channels/coding/plot_01_reed_solomon`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Reed-Solomon codes: recovering lost and corrupted symbols (1960)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A light client cannot download every block, so it relies on full nodes to prove fraud. That fails if the block producer publishes a header but withholds part of the data: nobody can then prove anything about it. Al-Bassam, Sonnino and Buterin extend the data with a Reed-Solomon code, so that any half of the shares rebuilds the block. To hide even one transaction the producer must withhold more than half of the shares, and a client sampling s random shares notices with probability">

.. only:: html

  .. image:: /api/gallery/channels/coding/images/thumb/sphx_glr_plot_02_data_availability_sampling_thumb.png
    :alt:

  :doc:`/api/gallery/channels/coding/plot_02_data_availability_sampling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fraud proofs and data-availability sampling (Al-Bassam, Sonnino and Buterin, 2018)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Interoperability
----------------

Moving value between chains: atomic swaps, light-client relays, and bridges that trust a committee.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Alice has coins on chain A, Bob on chain B, and neither will pay first. Tier Nolan&#x27;s protocol ties both payments to one secret. Alice locks her coins to Bob behind the hash of a secret, refundable to her at T_A; Bob locks his to Alice behind the same hash, refundable at T_B. Alice claims on B by revealing the secret, and Bob reads it there and claims on A. The swap is atomic if">

.. only:: html

  .. image:: /api/gallery/channels/interoperability/images/thumb/sphx_glr_plot_01_atomic_swaps_thumb.png
    :alt:

  :doc:`/api/gallery/channels/interoperability/plot_01_atomic_swaps`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Tier Nolan's atomic cross-chain swaps (2013)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="An Ethereum contract cannot see Bitcoin. BTC Relay let it check Bitcoin payments the way a light client does: relayers submit block headers, the contract checks that each links to a stored one and meets its proof-of-work target, and it follows the chain with the most work. A contract can then verify that a transaction is in a block of that chain under c confirmations, with a Merkle proof against the header&#x27;s root. Each header adds expected work">

.. only:: html

  .. image:: /api/gallery/channels/interoperability/images/thumb/sphx_glr_plot_02_btc_relay_thumb.png
    :alt:

  :doc:`/api/gallery/channels/interoperability/plot_02_btc_relay`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">BTC Relay: a Bitcoin light client in an Ethereum contract (2016)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Most bridges do not verify the other chain; they trust a committee to sign withdrawals, and are exactly as safe as its keys and the code that checks its signatures. In 2022 both failed. Ronin released funds on 5 of 9 validator signatures; one company ran four validators and still held permission to sign for a fifth, so a single breach yielded 173,600 ether and 25.5 million USDC. Wormhole&#x27;s Solana program trusted an account, supplied by the caller, saying that the guardians&#x27; signatures had been checked; a forged account minted 120,000 wrapped ether from nothing.">

.. only:: html

  .. image:: /api/gallery/channels/interoperability/images/thumb/sphx_glr_plot_03_bridge_exploits_thumb.png
    :alt:

  :doc:`/api/gallery/channels/interoperability/plot_03_bridge_exploits`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bridge failures: the Ronin and Wormhole exploits (2022)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Payment and state channels
--------------------------

Paying off chain with the chain as judge: one-way and duplex channels, revocation and penalties, general state channels, eltoo, and watchtowers.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Paying for a stream by the second on chain costs a transaction, and a fee, per payment. Jeremy Spilman&#x27;s channel needs two. The payer locks the channel&#x27;s capacity in a 2-of-2 output, after the payee has signed a refund that returns everything to the payer at a lock time. Each payment is a new transaction from that output, paying the payee a little more; the payer signs it and hands it over, and the payee countersigns and publishes only the last one. Mike Hearn built the scheme into bitcoinj the same year.">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_01_spilman_channels_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_01_spilman_channels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spilman and Hearn's one-way micropayment channels (2013)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A Spilman channel pays one way and is spent once its capacity has gone to the payee. Decker and Wattenhofer pair two of them, one in each direction, and reset the pair when one side runs dry, re-funding both from the current balances. Without penalties, the newest pair must beat every older one to the chain, and an invalidation tree of relative lock times sees to that: at every level, each replacement lowers the lock time by \delta, so where two branches part, the newer one is valid first and spends the shared parent. A tree of depth d with s lock-time values per level holds s^d resets, and closing waits for up to">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_02_duplex_channels_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_02_duplex_channels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Decker and Wattenhofer's duplex micropayment channels (2015)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Lightning ranks a channel&#x27;s states by punishment rather than by time locks, so a channel can be updated any number of times. Each party holds its own commitment transaction, signed by the other. It pays the counterparty at once, but its holder only after a delay, during which anyone with the revocation key can take the holder&#x27;s output instead. Moving to a new state, each party reveals the secret behind its old commitment&#x27;s revocation key. Publishing a revoked commitment then forfeits the whole channel to a counterparty that is watching.">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_03_lightning_revocation_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_03_lightning_revocation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Poon and Dryja's Lightning Network: revocation and penalties (2016)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="With contracts, a channel can be a judge rather than a set of transactions. An adjudicator contract holds both deposits; the parties sign successive versions of any state; and at the end one of them submits the latest. If it submits an old version, the other has a dispute period to submit a newer one, and the contract pays out the highest version it saw.">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_04_sprites_state_channels_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_04_sprites_state_channels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Sprites and general state channels (Miller et al., 2017)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Lightning&#x27;s penalty punishes mistakes as hard as theft: restore an old backup, publish it, and lose the channel. eltoo replaces punishment with replacement. Every state is an update transaction, which can spend the funding output or any earlier update, and a settlement, which pays that state&#x27;s balances after a delay. An old update on chain is simply overwritten by a newer one, and only the last update ever settles.">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_05_eltoo_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_05_eltoo`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">eltoo: channel updates without penalties (Decker, Russell and Osuntokun, 2018)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A Lightning party is safe only while it watches the chain: if it is offline for longer than the channel&#x27;s delay, a revoked commitment can be swept. A watchtower watches for it. After each update the party gives the tower a hint, half the revoked commitment&#x27;s txid, and a presigned penalty encrypted under the whole txid; the tower learns nothing until that commitment appears, and can then publish only a penalty that pays the party.">

.. only:: html

  .. image:: /api/gallery/channels/payment_channels/images/thumb/sphx_glr_plot_06_pisa_watchtowers_thumb.png
    :alt:

  :doc:`/api/gallery/channels/payment_channels/plot_06_pisa_watchtowers`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Watchtowers and PISA: guarding offline channel parties (McCorry et al., 2019)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Channel networks
----------------

Routing payments across many channels, and what the errors reveal.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Lightning routes a payment over several channels with hash time-locked contracts: each hop forwards the amount minus its fee, with an expiry a margin earlier than the one it was offered. The sender sees every channel&#x27;s capacity but not how it is split, which is meant to keep balances, and so payments, private.">

.. only:: html

  .. image:: /api/gallery/channels/routing/images/thumb/sphx_glr_plot_01_balance_probing_thumb.png
    :alt:

  :doc:`/api/gallery/channels/routing/plot_01_balance_probing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Balance probing and payment privacy in Lightning (Herrera-Joancomartí et al., 2019)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Scaling the chain
-----------------

Moving work off chain or splitting it up while keeping the chain's security: Plasma, sharding, and rollups.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Plasma runs a whole chain off chain. An operator produces its blocks and posts only their Merkle roots to a root-chain contract, which cannot check the transactions behind them. Coins stay safe because their owners can always exit: prove ownership on the root chain, then wait out a challenge period during which anyone can prove the exit wrong.">

.. only:: html

  .. image:: /api/gallery/channels/scaling/images/thumb/sphx_glr_plot_01_plasma_exit_games_thumb.png
    :alt:

  :doc:`/api/gallery/channels/scaling/plot_01_plasma_exit_games`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plasma: child chains secured by exit games (Poon and Buterin, 2017)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Splitting validators into shards multiplies throughput, but each shard is only as safe as its own committee. OmniLedger reshuffles validators into shards every epoch from unbiasable randomness, so an adversary cannot concentrate its validators in one committee. A committee of m drawn from N validators, M of them malicious, fails if a third or more of it is malicious, which is a hypergeometric tail:">

.. only:: html

  .. image:: /api/gallery/channels/scaling/images/thumb/sphx_glr_plot_02_omniledger_sharding_thumb.png
    :alt:

  :doc:`/api/gallery/channels/scaling/plot_02_omniledger_sharding`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">OmniLedger and sharding (Kokoris-Kogias et al., 2018)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A rollup runs transactions off chain but posts them, compressed, to the chain, so anyone can rebuild its state. Barry Whitehat&#x27;s roll_up and Buterin&#x27;s 2018 proposal added a succinct proof that the posted state root follows from the batch. The contract checks the proof at a fixed cost and never re-executes anything, so the gas per transaction falls toward the cost of its calldata:">

.. only:: html

  .. image:: /api/gallery/channels/scaling/images/thumb/sphx_glr_plot_03_zk_rollups_thumb.png
    :alt:

  :doc:`/api/gallery/channels/scaling/plot_03_zk_rollups`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">zk-rollups: validity proofs for batched transactions (2018)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="An optimistic rollup, as Adler and Quintyne-Collins proposed in 2019, posts its batches and state roots with no proof. A root becomes final once a challenge window has passed, and anyone who recomputes a batch and disagrees can prove fraud within it, taking the proposer&#x27;s bond. The proof is found by bisection, as in Arbitrum (Kalodner et al., 2018): the two sides compare intermediate state roots, halving the disputed range each round, until they disagree about one transaction, which the chain re-executes. A batch of n transactions needs">

.. only:: html

  .. image:: /api/gallery/channels/scaling/images/thumb/sphx_glr_plot_04_optimistic_rollups_thumb.png
    :alt:

  :doc:`/api/gallery/channels/scaling/plot_04_optimistic_rollups`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Optimistic rollups and fraud-proof challenge windows (2019)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/channels/coding/index.rst
   /api/gallery/channels/interoperability/index.rst
   /api/gallery/channels/payment_channels/index.rst
   /api/gallery/channels/routing/index.rst
   /api/gallery/channels/scaling/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: channels_python.zip </api/gallery/channels/channels_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: channels_jupyter.zip </api/gallery/channels/channels_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_