From 8a7e4e39d1f4af5f41a19316f0e5fee7c0eecd1d Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Mon, 4 Nov 2024 11:39:35 +0100 Subject: [PATCH 1/4] chore: remove mentioning of not spec'ed Route Broadcasting Protocol --- .../0001-interledger-architecture.md | 2 +- .../0031-dynamic-configuration-protocol.md | 14 +++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/0001-interledger-architecture/0001-interledger-architecture.md b/0001-interledger-architecture/0001-interledger-architecture.md index 877c6164..856d75c8 100644 --- a/0001-interledger-architecture/0001-interledger-architecture.md +++ b/0001-interledger-architecture/0001-interledger-architecture.md @@ -38,7 +38,7 @@ Connectors provide a service of forwarding packets and relaying money, and they Like the Internet protocol stack that inspired it, the Interledger protocol suite is divided into layers of protocols with different responsibilities. Lower-level protocols provide basic functionality that higher-level protocols depend on to provide more complex functionality. -> **Aside:** Not pictured in the diagram are configuration protocols including [IL-RFC-31: Interledger Dynamic Configuration Protocol](../0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md) and **Route Broadcasting Protocol**. These protocols are built on top of the Interledger Protocol layer and support it, but are not considered to be transport or application-layer protocols. +> **Aside:** Not pictured in the diagram are configuration protocols including [IL-RFC-31: Interledger Dynamic Configuration Protocol](../0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md) or a route broadcasting protocol (not specified yet). These protocols are built on top of the Interledger Protocol layer and support it, but are not considered to be transport or application-layer protocols. The following sections describe the general functions of each layer in the protocol suite. For an alternate explanation with detailed depictions of the protocols' data formats, see [IL-RFC-33: Relationship Between Protocols](../0033-relationship-between-protocols/0033-relationship-between-protocols.md). diff --git a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md index a586a032..85fdd0df 100644 --- a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md +++ b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md @@ -7,6 +7,7 @@ draft: 3 # Interledger Dynamic Configuration Protocol (ILDCP) v1 ## Prerequisites + This specification assumes the reader is familiar with the following documents: - [Interledger Architecture](../0001-interledger-architecture/0001-interledger-architecture.md) @@ -14,13 +15,14 @@ This specification assumes the reader is familiar with the following documents: ## Terminology -- A **node** is a participant in an Interledger network. It may be a [connector](../0001-interledger-architecture/0001-interledger-architecture.md#connectors), a sender or a receiver. +- A **node** is a participant in an Interledger network. It may be a [connector](../0001-interledger-architecture/0001-interledger-architecture.md#connectors), a sender or a receiver. - Nodes are connected to each other and the relationship between two nodes is either: - `parent` and `child` (one node is the `parent` of another node that is relatively its `child`), or, - `peer` and `peer` (two nodes are peered with one another). ## Overview -Interledger is a protocol suite that consists of several protocols including the [Bilateral Transfer Protocol](../0023-bilateral-transfer-protocol/0023-bilateral-transfer-protocol.md), the Route Broadcasting Protocol and others necessary for establishment, operation and maintenance of the network. Interledger Dynamic Configuration Protocol (ILDCP) is one of these protocols. + +Interledger is a protocol suite that consists of several protocols including the [Bilateral Transfer Protocol](../0023-bilateral-transfer-protocol/0023-bilateral-transfer-protocol.md) or [ILP over HTTP](../0035-ilp-over-http/0035-ilp-over-http.md) and others necessary for establishment, operation and maintenance of the network. Interledger Dynamic Configuration Protocol (ILDCP) is one of these protocols. In order to participate in the network a node must have an [ILP address](../0015-ilp-addresses/0015-ilp-addresses.md). This address is part of a heirarchical address space where child nodes MAY be allocated addresses within the address space of their parent node. This makes routing on the network more efficient than if all nodes had top-level addresses. @@ -40,6 +42,7 @@ Future versions of the protocol MAY exchange additional configuration informatio ## Protocol Detail ### Procedure + An exchange of configuration information is done using the following procedure. 1. A child node requests configuration information from the parent node @@ -47,7 +50,8 @@ An exchange of configuration information is done using the following procedure. 3. If the request cannot be processed, the parent node responds with an error ### Packet -The request and the response above are transferred in [ILP packets](../0027-interledger-protocol-4/0027-interledger-protocol-4.md#specification). + +The request and the response above are transferred in [ILP packets](../0027-interledger-protocol-4/0027-interledger-protocol-4.md#specification). The `fulfillment` of the response packet is always a zero-filled 32 byte octet string, therefore the condition is always the SHA-256 hash digest of that, i.e. the Base64 decoded value of `Zmh6rfhivXdsj8GLjp+OIAiXFIVu4jOzkCpZHQ1fKSU=`. @@ -64,7 +68,6 @@ The packet exchange goes as follows: - The `executionCondition` of the ILP packet is `Zmh6rfhivXdsj8GLjp+OIAiXFIVu4jOzkCpZHQ1fKSU=` in Base64 format - The `destination` address of the ILP packet is `peer.config` - The `data` of the ILP packet is empty (size: 0) - - Response - The `type` of the ILP packet is `ILP Fulfill` (type id: 13) - The `fulfillment` of the ILP packet is a 32-byte octet string all filled with zeros @@ -72,7 +75,6 @@ The packet exchange goes as follows: - `Variable-length octet string`: An ILP address that the child should use, encoded as an `ASCII` string - `Uint8`: An unsigned 8-bit integer indicating the asset scale that should be used for packets exchanged with the parent - `Variable-length octet string`: An asset code, encoded as a `UTF-8` string, indicating the settlement asset used between the peers - - Error - The `type` of the ILP packet is `ILP Reject` (type id: 14) - The `code` of the ILP packet is an appropriate error code @@ -81,7 +83,9 @@ The packet exchange goes as follows: - The `data` of the ILP packet is empty (size: 0) or MAY contain further information for debugging the error. ### ASN.1 Definition + The ASN.1 definition of ILP packets is described in [InterledgerProtocol.asn](../asn1/InterledgerProtocol.asn) and Dynamic Configuration Protocol data in [DynamicConfigurationProtocol.asn](../asn1/DynamicConfigurationProtocol.asn). ### Encoding + All ASN.1 types are encoded using [Octet Encoding Rules](../0030-notes-on-oer-encoding/0030-notes-on-oer-encoding.md) as is the norm with all Interledger protocols. From 8ff0c2a851b89b84d5583fb59a56896c8471461f Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 19 Nov 2024 10:22:22 +0100 Subject: [PATCH 2/4] Update 0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md Co-authored-by: Max Kurapov --- .../0031-dynamic-configuration-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md index 85fdd0df..9a1d9464 100644 --- a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md +++ b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md @@ -22,7 +22,7 @@ This specification assumes the reader is familiar with the following documents: ## Overview -Interledger is a protocol suite that consists of several protocols including the [Bilateral Transfer Protocol](../0023-bilateral-transfer-protocol/0023-bilateral-transfer-protocol.md) or [ILP over HTTP](../0035-ilp-over-http/0035-ilp-over-http.md) and others necessary for establishment, operation and maintenance of the network. Interledger Dynamic Configuration Protocol (ILDCP) is one of these protocols. +Interledger is a protocol suite that consists of several protocols such as the [Bilateral Transfer Protocol](../0023-bilateral-transfer-protocol/0023-bilateral-transfer-protocol.md), [ILP over HTTP](../0035-ilp-over-http/0035-ilp-over-http.md) and others necessary for establishment, operation and maintenance of the network. Interledger Dynamic Configuration Protocol (ILDCP) is one of these protocols. In order to participate in the network a node must have an [ILP address](../0015-ilp-addresses/0015-ilp-addresses.md). This address is part of a heirarchical address space where child nodes MAY be allocated addresses within the address space of their parent node. This makes routing on the network more efficient than if all nodes had top-level addresses. From 483a051c48f3aa4b69be3c1f4cc5067545d9d148 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 19 Nov 2024 10:22:59 +0100 Subject: [PATCH 3/4] Update 0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md Co-authored-by: Max Kurapov --- .../0031-dynamic-configuration-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md index 9a1d9464..d6c2e2de 100644 --- a/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md +++ b/0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md @@ -51,7 +51,7 @@ An exchange of configuration information is done using the following procedure. ### Packet -The request and the response above are transferred in [ILP packets](../0027-interledger-protocol-4/0027-interledger-protocol-4.md#specification). +Requests and responses are transferred in [ILP packets](../0027-interledger-protocol-4/0027-interledger-protocol-4.md#specification). The `fulfillment` of the response packet is always a zero-filled 32 byte octet string, therefore the condition is always the SHA-256 hash digest of that, i.e. the Base64 decoded value of `Zmh6rfhivXdsj8GLjp+OIAiXFIVu4jOzkCpZHQ1fKSU=`. From 0f5a771e8c9ebfe4e133e39c8fa2c2f3b52e2e7b Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 19 Nov 2024 10:27:59 +0100 Subject: [PATCH 4/4] clarify RBP in relationship doc --- .../0033-relationship-between-protocols.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/0033-relationship-between-protocols/0033-relationship-between-protocols.md b/0033-relationship-between-protocols/0033-relationship-between-protocols.md index 638190a8..6223eed5 100644 --- a/0033-relationship-between-protocols/0033-relationship-between-protocols.md +++ b/0033-relationship-between-protocols/0033-relationship-between-protocols.md @@ -7,11 +7,13 @@ draft: 2 # Relationship between Protocols ## Prerequisites + This document assumes the reader is familiar with the following document: - [Interledger Architecture](../0001-interledger-architecture/0001-interledger-architecture.md) ## Terminology + - A **node** is a participant in an Interledger network. It may be a [connector](../0001-interledger-architecture/0001-interledger-architecture.md#connectors), a sender or a receiver. - A **payment** is sending value from one to another but it doesn't necessarily mean settled, as is explained below. In the Interledger network, a payment could mean a **node-to-node** payment or an **end-to-end** payment. - A **node-to-node** payment means the intention of transferring value of a node (a connector, an endpoint sender, or an endpoint receiver) to another node which is directly connected to the sender node. @@ -23,12 +25,15 @@ This document assumes the reader is familiar with the following document: - Refer to [Interledger Architecture](../0001-interledger-architecture/0001-interledger-architecture.md) and [Perspective](#perspective). ## Motivation + Because the Interledger Protocol suite consists of several protocols and some related specifications, it can be difficult to understand the relationship between each of the protocols. This document attempts to provide an overview and mental model of how the components fit together. It is primarily intended for implementers of parts of the Interledger stack but may also be useful for others who wish to understand how Interledger works as a whole. A mental model is what a reader assumes something to be, reading some explanation. The mental model helps the reader predicting the behavior of what is explained even if the details are not given at that time. ## Scope + The scope of this document is the explication of the relationship between the Interledger protocols, and the details for it are out of scope. Some references are given for it though. i.e. This document draws a whole, big picture of ILP. ## Perspective + There are two diagrams, one is for the macro view that shows the main elements and its IP layer connections, another is for the micro view that shows protocols, the interaction between programs, and the other details. The alphabets (A-C) and numbers (1-15), that are shown in the diagrams as **red characters**, are explained briefly in the [Elements and Brief Explanations](#elements-and-brief-explanations) section. @@ -44,7 +49,9 @@ This is an enlarged diagram of the above diagram, that shows mainly `Node A`, `N ![Perspective of connections](images/perspective-protocols.svg) ### Elements and Brief Explanations + #### Connections + - (A) BTP over WebSocket - **Node** to **Node** connection - In order to exchange payments, configuration and routing information, a node MUST have secure communication channels with its peers. The current implementation uses WebSockets for it. @@ -57,6 +64,7 @@ This is an enlarged diagram of the above diagram, that shows mainly `Node A`, `N - To determine end-to-end payment information such as a shared secret, a destination address and so forth, an application connects to SPSP server over HTTPS. #### Protocols + - Link Layer Protocol - (1) BTP - [Bilateral Transfer Protocol 2.0 (BTP/2.0)](../0023-bilateral-transfer-protocol/0023-bilateral-transfer-protocol.md) @@ -84,10 +92,12 @@ This is an enlarged diagram of the above diagram, that shows mainly `Node A`, `N - DCP is a protocol built on top of ILP, and is used in order to exchange node information such as an ILP address. - DCP data is put into the extensible data area of ILP packets. - (8) RBP - - RBP is a protocol built on top of ILP, and is used for transferring routing information to build routing tables. - - RBP data is put into the extensible data area of ILP packets. + - A Route Broadcasting Protocol is thought to be a protocol built on top of ILP, and would be used for transferring routing information to build routing tables. + - RBP data would be put into the extensible data area of ILP packets. + - RBP is an idea that does not exist yet. #### Data Structure and Encoding + - (9) ASN.1 - [ASN.1 Project](https://www.itu.int/en/ITU-T/asn1/) - ASN.1 is used in order to specify data structure (order, type, and length). @@ -99,6 +109,7 @@ This is an enlarged diagram of the above diagram, that shows mainly `Node A`, `N - Canonical OER is one of the specifications that define the encoding rule. #### Functions + The functions shown below are just concepts, so their exact form may differ between implementations. - (11) Account Module