Merge pull request #44 from cardano-scaling/js/cddls

Provide CDDLs for NTN, relocate Mini-protocols, relocate ChainDB

Author: ch1bo

src/SUMMARY.md

@@ -1,32 +1,40 @@
 # Summary
 
 - [Introduction](introduction/README.md)
-- [Blueprints]()
-  - [Network](network/README.md)
-    - [Multiplexing](network/multiplexing.md)
-    - [Mini-protocols](network/mini-protocols.md)
-    - [Handshake Mini-protocol](network/handshake.md)
-  - [Consensus](consensus/README.md)
-    - [Chain validity](consensus/chainvalid.md)
-    - [Chain selection](consensus/chainsel.md)
-    - [Forging new blocks](consensus/forging.md)
-    - [Multi-era considerations](consensus/multiera.md)
-  - [Storage](storage/README.md)
-    - [Semantics of storage mini-protocols](storage/diffusion.md)
-      - [ChainSync](storage/miniprotocols/chainsync.md)
-      - [BlockFetch](storage/miniprotocols/blockfetch.md)
-    - [ChainDB format](storage/chaindb.md)
-  - [Mempool](mempool/README.md)
-    - [TxSubmission2](mempool/txsubmission2.md)
-  - [Ledger](ledger/README.md)
-    - [Transaction fee](ledger/transaction-fee.md)
-    - [Block Validation](ledger/block-validation.md)
-  - [Plutus](plutus/README.md)
-    - [Syntax](plutus/syntax.md)
-    - [Builtin Types and Functions](plutus/builtin.md)
-    - [The CEK Machine](plutus/cek.md)
-  - [API reference]()
-    - [Node-To-Client (NTC)](api/node-to-client.md)
+- [Network](network/README.md)
+  - [Multiplexing](network/multiplexing.md)
+  - [Mini-protocols](network/mini-protocols.md)
+    - [Handshake](network/node-to-node/handshake/README.md)
+    - [ChainSync](network/node-to-node/chainsync/README.md)
+    - [BlockFetch](network/node-to-node/blockfetch/README.md)
+    - [TxSubmission2](network/node-to-node/txsubmission2/README.md)
+    - [KeepAlive](network/node-to-node/keep-alive/README.md)
+    - [PeerSharing]()
+- [Consensus](consensus/README.md)
+  - [Chain validity](consensus/chainvalid.md)
+  - [Chain selection](consensus/chainsel.md)
+  - [Forging new blocks](consensus/forging.md)
+  - [Multi-era considerations](consensus/multiera.md)
+- [Storage](storage/README.md)
+  - [`cardano-node`'s ChainDB](storage/cardano-node-chaindb/README.md)
+- [Mempool](mempool/README.md)
+- [Ledger](ledger/README.md)
+  - [Transaction fee](ledger/transaction-fee.md)
+  - [Block Validation](ledger/block-validation.md)
+  - [CDDL Specs](ledger/cddls.md)
+- [Plutus](plutus/README.md)
+  - [Syntax](plutus/syntax.md)
+  - [Builtin Types and Functions](plutus/builtin.md)
+  - [The CEK Machine](plutus/cek.md)
+- [Client interfaces](client/README.md)
+  - [NTC](client/node-to-client/README.md)
+    - [Handshake]()
+    - [LocalStateQuery](client/node-to-client/state-query/README.md)
+    - [LocalTxSubmission]()
+    - [TxMonitor]()
+    - [LocalChainSync]()
+  - [UTxO-RPC](client/utxo-rpc/README.md)
+- [Codec basics](codecs/README.md)
 
 ---
 

src/client/README.md

@@ -0,0 +1,38 @@
+# Client interfaces
+
+Node implementations may offer interfaces to clients for submitting new data to
+the network (transactions) as well as query data from the node. The spectrum of
+protocols that could serve this purpose is open and the choice is free for each
+implementation. Here we aggregate some interfaces that have been implemented for
+enabling this interaction:
+
+- the [Node-To-Client (NTC)](./node-to-client/) interface as introduced by [cardano-node], which is very similar to the Node-To-Node (NTN) [network](../network) protocols,
+- the [UTxO RPC](utxo-rpc/README.md) interface as a standard interface shared
+  with other UTxO-based blockchains.
+
+Below we present a table with clients and servers that implement each protocol:
+
+| Server         | NTC | UTxO RPC |
+|:---------------|-----|----------|
+| [cardano-node] | ✅  | ❔       |
+| [dingo]        | ✅  | ✅       |
+| [amaru]        | ❔  | ❔       |
+
+<br/>
+
+| Client        | NTC | UTxO RPC |
+|:--------------|-----|----------|
+| [cardano-cli] | ✅  | ⬜       |
+| [pallas]      | ✅  | ❔       |
+| [gouroboros]  | ✅  | ❔       |
+
+> [!NOTE]
+>
+> Please help us keep this list up-to-date by [suggesting an edit](https://github.com/cardano-scaling/cardano-blueprint/edit/main/src/client/README.md).
+
+[cardano-node]: https://github.com/IntersectMBO/cardano-node
+[cardano-cli]: https://github.com/IntersectMBO/cardano-cli
+[dingo]: https://github.com/blinklabs-io/dingo
+[gouroboros]: https://github.com/blinklabs-io/gouroboros
+[amaru]: https://github.com/pragma-org/amaru/
+[pallas]: https://github.com/txpipe/pallas

src/client/node-to-client/README.md

@@ -0,0 +1,18 @@
+# Node-To-Client (NTC)
+
+`cardano-node` implements a set of mini-protocols that follow rules very similar
+to those in the Node-To-Node interface, except that they communicate through a
+named pipe. As these protocols establish connections to local clients there is
+trust between peers and consequently they behave more like traditional
+client/server APIs.
+
+In particular, these mini-protocols will also be wrapped by a
+[multiplexer](../../network/multiplexing.md).
+
+These mini-protocols are:
+
+- [Handshake](): to negotiate the versions used in the connection,
+- [LocalTxSubmission](): to submit transactions to the network,
+- [LocalStateQuery](state-query): to query for information about the ledger state,
+- [TxMonitor](): to monitor the status of transactions,
+- [LocalChainSync](): to retrieve chains of blocks from the node.

src/api/node-to-client.md renamed to src/client/node-to-client/state-query/README.md

@@ -1,18 +1,9 @@
-# Node-To-Client (N2C)
-
-A cardano node may offer a client-facing API using the [network protocols](../network). This interface is slightly different than the Node-to-Node (N2N) style of communication as there is trust between peers and consequently behaves more like traditional client/server APIs.
-
-This document serves as concrete API reference for the various N2C protocols and currently only covers the local state query API.
-
-> [!NOTE]
-> The way to establish connections to an N2C server may differ from one implementation to another. The following sections assume that you have an established connection and negotiated a protocol version possibly through the [handshake protocol](../network/handshake.md).
-
-## LocalStateQuery
+# LocalStateQuery
 
 > Protocol version: V19
 
 > [!WARNING]
-> TODO: Explain how to use and relate state diagram to full protocol in [network](../network) chapter?
+> TODO: Explain how to use and relate state diagram to full protocol in [network](../../../network) chapter?
 
 <details>
   <summary> Full mini-protocol state diagram</summary>
@@ -44,7 +35,7 @@ Client-side view on the protocol[^1]:
               ┌───────────────┐ MsgDone
        ╭─────▶│     Idle      ├────────▶ ○
        │      └───────┬───────┘
-       │   MsgAcquire │ 
+       │   MsgAcquire │
        │              ▼  ╭────────╮
        │      ┌──────────┴────┐   │ MsgReAcquire
        ╰──────┤   Acquired    │◀──╯
@@ -91,11 +82,11 @@ _Since: v9_
 Query the chain's start time as a `UTCTime`.
 
 ```cddl
-{{#include cddl/local-state-query.cddl:api}}
+{{#include messages.cddl:api}}
 ```
 
 ```cddl
-{{#include cddl/getSystemStart.cddl}}
+{{#include getSystemStart.cddl}}
 ```
 
 Example query:
@@ -123,4 +114,3 @@ Example response:
 
 > [!WARNING]
 > TODO: Era-specific query with an involved answer
-

src/api/examples/getSystemStart/query.cbor renamed to src/client/node-to-client/state-query/examples/getSystemStart/query.cbor

@@ -0,0 +1,5 @@
+# UTxO-RPC
+
+A gRPC interface for UTxO Blockchains that is implemented by a few Cardano components.
+
+See the official website [utxorpc.org](https://utxorpc.org/) for a full introduction and documentation.

src/api/examples/getSystemStart/result.cbor renamed to src/client/node-to-client/state-query/examples/getSystemStart/result.cbor

@@ -0,0 +1,50 @@
+# Codec basics
+
+Common encoding format and binary interface description used across blueprints.
+
+## CBOR
+
+TODO: justify the use of CBOR and briefly describe it. Mention `cbor2diag.rb`
+and related tools. (I believe it is the `cbor-tools` Ruby gem).
+
+## CDDL
+
+CDDLs are often times the combination of partial CDDLs definitions
+from Network, Consensus and Ledger layers. To combine all these, we
+will make use of the `cddlc` tool specified in [this
+RFC](https://datatracker.ietf.org/doc/draft-ietf-cbor-cddl-modules/). This
+tool provide meaning to the `;# import` and `;# include` directives to
+have a modular system over CDDL definitions.
+
+The CDDL specs presented in this section will make use of the
+following base definitions that we will consider defined globally:
+
+```cddl
+{{#include base.cddl:0:18}}
+```
+
+In addition, we add the following types to represent tag-encoded
+alternatives, commonly used at the consensus level to encode a
+different tag for each one of the eras in the Cardano blockchain:
+
+```cddl
+{{#include base.cddl:20:}}
+```
+
+These definitions are made available in the
+[`base.cddl`](base.cddl)
+file which we will import qualified with `;# import base as base`.
+
+On the other side, Ledger CDDL specs are fully self-contained for each
+era, hence there are repetitions of basic types, which we will bring
+in qualified by the era name. We will usually import the Ledger CDDLs as:
+
+```cddl
+;# include byron as byron
+;# include shelley as shelley
+;# include allegra as allegra
+;# include mary as mary
+;# include alonzo as alonzo
+;# include babbage as babbage
+;# include conway as conway
+```