From fa6e8f66e15f2bc55ee233f655c1be6e9f6fb229 Mon Sep 17 00:00:00 2001 From: Stefan Thomas Date: Wed, 5 Jul 2017 15:24:38 -0700 Subject: [PATCH 1/3] docs(echo): describe a basic echo protocol --- 0000-echo-protocol/0000-echo-protocol.md | 41 ++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 0000-echo-protocol/0000-echo-protocol.md diff --git a/0000-echo-protocol/0000-echo-protocol.md b/0000-echo-protocol/0000-echo-protocol.md new file mode 100644 index 00000000..40e9e8d6 --- /dev/null +++ b/0000-echo-protocol/0000-echo-protocol.md @@ -0,0 +1,41 @@ +# Echo Protocol + +## Introduction + +In order to monitor the health of an internetworked system, it is often useful to be able to send test messages. However, not every participant of the system will have multiple points of access to test between or, if they do, they may want to test additional routes. + +In the Internet system, a mechanism is provided for sending a message to an arbitary host and receiving a response back. This mechanism is coloquially known as a "ping" and allows users to test their connectivity against countless Internet hosts. We would like to provide a similar mechanism for Interledger. + +## Scope + +It is already possible to test end-to-end connectivity in Interledger using the quoting mechanism. By requesting a quote, we can check if there is theoretically liquidity between our own account and the destination account. However, this does not prove the liquidity is actually available and it does not say anything about the availability of liquidity in the opposite direction. The Interledger Echo Protocol is designed to be able to fully exercise liquidity in both directions. + +The echo protocol is designed to test uptime, latency and cost. It is not designed to debug routing issues and does not provide additional diagnostic information about the state of routing. This use case would be better served by a separate traceroute mechanism. + +All Interledger implementations should implement the echo service, unless they have a specific reason not to, such as security or privacy concerns. + +## Terminology + +* The **Client** is the Interledger implementation initiating the echo request. +* The **Mirror** is the Interledger implementation responding to the echo request. +* **Source amount** is the amount debited to the sender of an ILP payment. +* **Destination amount** is the amount credited to the recipient of an ILP payment. + +## Protocol + +1. The Client send a quote request with a destination ILP address of `[mirror's ilp address].echo.[client's ilp address]` and a destination amount of `0`. If the combined address is too long, the client aborts with an error. +2. Upon receiving the quote request, the Mirror initiates a quote request of their own for the Client's ILP address with an amount of `0`. +3. Upon receiving the quote response, the Mirror responds to the Client's quote request as if its destination amount had been the source amount of the quote response from step 2. +4. Upon receiving the quote response, the Client sends a payment using the quoted amount from step 3 and the same destination ILP address and amount as in step 1. The condition for the payment is the hash of a random nonce. The memo for the payment is the string "ECHO" followed by a space character (" "), followed by a UUID, encoded as an ASCII string. +5. Upon receiving the prepared transfer, the Mirror initiates a payment to the Client's ILP address with an amount of `0` using the incoming destination amount as the outgoing source amount. +6. Upon receiving the prepared transfer, the Client fulfills it. From here, the payment completes normally. + +If a Client wishes to query the bidirectional liquidity without making a payment, it may stop before step 4. + +If an error occurs between steps 5 and 6, the Mirror relays the error to the client, the same way a connector would relay an error. + +## Recommended Uses + +Participants of the Interledger network may use this mechanism to test their own connectivity by sending pings to one or more destinations that are known to support the protocol described in this document. + +A monitoring service that is testing the availability of different ILP connectors may send pings to these connectors from various sources. Connectors that with to use this monitoring service must support the protocol described in this document. From 631d60fda250c3d53893d7c9c5bf8df8280dddee Mon Sep 17 00:00:00 2001 From: BobWay Date: Wed, 5 Jul 2017 18:43:26 -0500 Subject: [PATCH 2/3] Update 0000-echo-protocol.md Fixed a few typos --- 0000-echo-protocol/0000-echo-protocol.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/0000-echo-protocol/0000-echo-protocol.md b/0000-echo-protocol/0000-echo-protocol.md index 40e9e8d6..8377d759 100644 --- a/0000-echo-protocol/0000-echo-protocol.md +++ b/0000-echo-protocol/0000-echo-protocol.md @@ -10,7 +10,7 @@ In the Internet system, a mechanism is provided for sending a message to an arbi It is already possible to test end-to-end connectivity in Interledger using the quoting mechanism. By requesting a quote, we can check if there is theoretically liquidity between our own account and the destination account. However, this does not prove the liquidity is actually available and it does not say anything about the availability of liquidity in the opposite direction. The Interledger Echo Protocol is designed to be able to fully exercise liquidity in both directions. -The echo protocol is designed to test uptime, latency and cost. It is not designed to debug routing issues and does not provide additional diagnostic information about the state of routing. This use case would be better served by a separate traceroute mechanism. +The echo protocol is designed to test uptime, latency and cost. It is not designed to debug routing issues and does not provide additional diagnostic information about the state of routing. That use case would be better served by a separate traceroute mechanism. All Interledger implementations should implement the echo service, unless they have a specific reason not to, such as security or privacy concerns. @@ -18,12 +18,12 @@ All Interledger implementations should implement the echo service, unless they h * The **Client** is the Interledger implementation initiating the echo request. * The **Mirror** is the Interledger implementation responding to the echo request. -* **Source amount** is the amount debited to the sender of an ILP payment. +* **Source amount** is the amount debited from the sender of an ILP payment. * **Destination amount** is the amount credited to the recipient of an ILP payment. ## Protocol -1. The Client send a quote request with a destination ILP address of `[mirror's ilp address].echo.[client's ilp address]` and a destination amount of `0`. If the combined address is too long, the client aborts with an error. +1. The Client sends a quote request with a destination ILP address of `[mirror's ilp address].echo.[client's ilp address]` and a destination amount of `0`. If the combined address is too long, the client aborts with an error. 2. Upon receiving the quote request, the Mirror initiates a quote request of their own for the Client's ILP address with an amount of `0`. 3. Upon receiving the quote response, the Mirror responds to the Client's quote request as if its destination amount had been the source amount of the quote response from step 2. 4. Upon receiving the quote response, the Client sends a payment using the quoted amount from step 3 and the same destination ILP address and amount as in step 1. The condition for the payment is the hash of a random nonce. The memo for the payment is the string "ECHO" followed by a space character (" "), followed by a UUID, encoded as an ASCII string. @@ -38,4 +38,4 @@ If an error occurs between steps 5 and 6, the Mirror relays the error to the cli Participants of the Interledger network may use this mechanism to test their own connectivity by sending pings to one or more destinations that are known to support the protocol described in this document. -A monitoring service that is testing the availability of different ILP connectors may send pings to these connectors from various sources. Connectors that with to use this monitoring service must support the protocol described in this document. +A monitoring service that is testing the availability of different ILP connectors may send pings to these connectors from various sources. Connectors that wish to use this monitoring service must support the protocol described in this document. From 6a98d78e914b4fff3e3d9523949b94d6b7a2a7bf Mon Sep 17 00:00:00 2001 From: Stefan Thomas Date: Fri, 7 Jul 2017 06:55:17 -0700 Subject: [PATCH 3/3] docs(echo): simplify protocol --- 0000-echo-protocol/0000-echo-protocol.md | 39 ++++++++++++++++++------ 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/0000-echo-protocol/0000-echo-protocol.md b/0000-echo-protocol/0000-echo-protocol.md index 8377d759..ccd26e02 100644 --- a/0000-echo-protocol/0000-echo-protocol.md +++ b/0000-echo-protocol/0000-echo-protocol.md @@ -23,16 +23,35 @@ All Interledger implementations should implement the echo service, unless they h ## Protocol -1. The Client sends a quote request with a destination ILP address of `[mirror's ilp address].echo.[client's ilp address]` and a destination amount of `0`. If the combined address is too long, the client aborts with an error. -2. Upon receiving the quote request, the Mirror initiates a quote request of their own for the Client's ILP address with an amount of `0`. -3. Upon receiving the quote response, the Mirror responds to the Client's quote request as if its destination amount had been the source amount of the quote response from step 2. -4. Upon receiving the quote response, the Client sends a payment using the quoted amount from step 3 and the same destination ILP address and amount as in step 1. The condition for the payment is the hash of a random nonce. The memo for the payment is the string "ECHO" followed by a space character (" "), followed by a UUID, encoded as an ASCII string. -5. Upon receiving the prepared transfer, the Mirror initiates a payment to the Client's ILP address with an amount of `0` using the incoming destination amount as the outgoing source amount. -6. Upon receiving the prepared transfer, the Client fulfills it. From here, the payment completes normally. - -If a Client wishes to query the bidirectional liquidity without making a payment, it may stop before step 4. - -If an error occurs between steps 5 and 6, the Mirror relays the error to the client, the same way a connector would relay an error. +1. The Client requests a quote by source amount using the following details: + - Source amount: A small amount considered (by the Client) to be sufficient for a round trip + - Destination ILP address: Mirror's ILP address +2. Upon receiving a quote response, the Client sends a payment using the following details: + - Source amount: The same source amount as in step 1 + - Destination amount: The quoted destination amount from the quote response + - Destination ILP address: Mirror's ILP address + - Data: The string `PING` followed by a newline character (a 0x0A byte), followed by a UUID in canonical textual representation, followed by another newline character, followed by the Client's ILP address. + + Example: + ``` + PING + 0c009642-f64c-45c7-b9e8-a57c95a60556 + example.myledger.test + ``` +3. Upon receiving the prepared transfer, the Mirror initiates a payment using the following details: + - Source amount: Same as the incoming destination amount + - Destination amount: 0 + - Destination ILP address: Client's ILP address (taken from the data field of the incoming payment) + - Data: The string `PONG` followed by a newline character (a 0x0A byte), followed by the UUID taken from the incoming payment's data field. + + Example: + ``` + PONG + 0c009642-f64c-45c7-b9e8-a57c95a60556 + ``` +4. Upon receiving the prepared transfer, the Client fulfills it. From here, the payment completes normally. + +If an error occurs between steps 3 and 4, the Mirror should relay the error by rejecting the incoming transfer the same way a connector would when relaying an error. ## Recommended Uses