docs: network transaction builder (#1074)

Author: Mirko-von-Leipzig

crates/store/src/genesis/config/mod.rs

@@ -178,7 +178,7 @@ impl GenesisConfig {
             // yet to be deployed. An account is deployed onchain along with its first
             // transaction which results in a non-zero nonce onchain.
             //
-            // The genesis block is special in that accounts are "deplyed" without transactions and
+            // The genesis block is special in that accounts are "deployed" without transactions and
             // therefore we need bump the nonce manually to uphold this invariant.
             let wallet_delta = AccountDelta::new(
                 wallet_account.id(),

docs/src/SUMMARY.md

@@ -27,6 +27,7 @@
   - [RPC](./developer/rpc.md)
   - [Store](./developer/store.md)
   - [Block producer](./developer/block-producer.md)
+  - [Network transaction builder](./developer/ntx-builder.md)
 - [Common issues other oddities](./developer/oddities.md)
 
 ---

docs/src/developer/codebase.md

@@ -10,10 +10,11 @@ instead simply serve to enforce code organisation and decoupling.
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `node`                    | The node executable. Configure and run the node and its components.                                                                                      |
 | `faucet`                  | A reference faucet app implementation used by the official Miden faucet.                                                                                 |
-| `remote-prover`           | Remote prover executables. Includes workers and proxies.                                                                                                  |
-| `remote-prover-client`    | Remote prover client implementation.                                                                                                                    |
+| `remote-prover`           | Remote prover executables. Includes workers and proxies.                                                                                                 |
+| `remote-prover-client`    | Remote prover client implementation.                                                                                                                     |
 | `block-producer`          | Block-producer component implementation.                                                                                                                 |
 | `store`                   | Store component implementation.                                                                                                                          |
+| `ntx-builder`             | Network transaction builder component implementation.                                                                                                    |
 | `rpc`                     | RPC component implementation.                                                                                                                            |
 | `proto`                   | Contains and exports all protobuf definitions.                                                                                                           |
 | `rpc-proto`               | Contains the RPC protobuf definitions. Currently this is an awkward clone of `proto` because we re-use the definitions from the internal protobuf types. |

docs/src/developer/ntx-builder.md

@@ -0,0 +1,45 @@
+# Network Transaction Builder Component
+
+The network transaction builder (NTB) is responsible for driving the state of network accounts.
+
+## What is a network account
+
+Network accounts are a special type of fully public account which contains no authentication and
+whose state can therefore be updated by anyone (in theory). Such accounts are required when publicly
+mutable state is needed.
+
+The issue with publicly mutable state is that transactions against an account must be sequential
+and require the previous account commitment in order to create the transaction proof. This conflicts
+with Miden's client side proving and concurrency model since users would race each other to submit
+transactions against such an account.
+
+Instead the solution is to have the network be responsible for driving the account state forward,
+and users can interact with the account using notes. Notes don't require a specific ordering and
+can be created concurrently without worrying about conflicts. We call these network notes and they
+always target a specific network account.
+
+A network transaction is a transaction which consumes and applies a set of network notes to a
+network account. There is nothing special about the transaction itself - it can only be identified
+by the fact that it updates the state of a network account.
+
+## Limitations
+
+At present, we artificially limit this such that only this component may create transactions against
+network accounts. This is enforced at the RPC layer by disallowing network transactions entirely in
+that component. The NTB skirts around this by submitting its transactions directly to the
+block-producer.
+
+This limitation is there to prevent complicating the NTBs implementation while the protocol and
+definitions of network accounts, notes and transactions mature.
+
+## Implementation
+
+On startup the mempool loads all unconsumed network notes from the store. From there it monitors
+the mempool for events which would impact network account state. This communication takes the form
+of an event stream via gRPC.
+
+The NTB periodically selects an arbitrary network account with available network notes and creates
+a network transaction for it.
+
+The block-producer remains blissfully unaware of network transactions. From its perspective a
+network transaction is simply the same as any other.

docs/src/operator/architecture.md

@@ -1,13 +1,14 @@
 # Node architecture
 
-The node itself consists of three distributed components: store, block-producer and RPC. We also provide a reference
-faucet implementation which we use to distribute testnet and devnet tokens.
+The node itself consists of four distributed components: store, block-producer, network transaction builder, and RPC.
+We also provide a reference faucet implementation which we use to distribute testnet and devnet tokens.
 
 The components can be run on separate instances when optimised for performance, but can also be run as a single process
-for convenience. At the moment both of Miden's public networks (testnet and devnet) are operating in single process
+for convenience. The exception to this is the network transaction builder which can currently only be run as part of
+the single process. At the moment both of Miden's public networks (testnet and devnet) are operating in single process
 mode.
 
-The inter-component communication is done using a gRPC API wnich is assumed trusted. In other words this _must not_ be
+The inter-component communication is done using a gRPC API which is assumed trusted. In other words this _must not_ be
 public. External communication is handled by the RPC component with a separate external-only gRPC API.
 
 ![node architecture](../resources/operator_architecture.svg)
@@ -40,6 +41,15 @@ proved, and then periodically aggregated into a block. This block is then proved
 Proof generation in production is typically outsourced to a remote machine with appropriate resources. For convenience,
 it is also possible to perform proving in-process. This is useful when running a local node for test purposes.
 
+## Network transaction builder
+
+The network transaction builder monitors the mempool for network notes, and creates transactions consuming these.
+We call these network transactions and at present this is the only entity that is allowed to create such transactions.
+This restriction is will be lifted in the future, but for now this component _must_ be enabled to have support for
+network transactions.
+
+The mempool is monitored via a gRPC event stream served by the block-producer.
+
 ## Faucet
 
 A stand-alone binary which serves a webpage where users can request tokens from a customizable faucet account. The