From 4aa3b86837a42c8f3e2b3e7feafa7db8303c249e Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 10:58:30 -0700 Subject: [PATCH 01/20] Add glossary --- docs/markdown/glossary.md | 263 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/markdown/glossary.md diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md new file mode 100644 index 0000000..efa169a --- /dev/null +++ b/docs/markdown/glossary.md @@ -0,0 +1,263 @@ +# Glossary + +This glossary provides definitions for key terms in the Interledger ecosystem. + +## Account + +An accounting relationship between two Interledger participants. +In Interledger, two participants establish an account with one another to track the current obligations they hold with one another. + +## Address + +See instead: [Interledger Address](#interledger-address) + +## Application Layer + +The set of protocols built upon the Transport Layer that communicate payment details between senders and receivers. + +Application Layer protocols specify all of the data and methods required to set up a payment for a specific category of use cases or applications. For example, the Simple Payment Setup Protocol uses WebFinger and HTTPS for account detail lookup. + +## Arbitrage + +The practice of doing cyclic transactions which start and end on the same ledger, or groups of simultaneous transactions which add up to one cyclic transaction. The goal is to achieve a destination amount which is higher than the source amount by taking advantage of fluctuations in exchange rates. + +## Asset + +Something you can own. Can be a physical and unique item, a quantity of a physical substance, a specific physical collection of coins and banknotes, a non-physical quantity of currency, a non-physical claim to a resource, a reputation for keeping one's word, someone else's intention to obey the terms of a contract, etc. Some types of assets can be more easily traded on a ledger than others. Also, for some asset pairs it is easier to determine a fair exchange rate than for others. + +## Balance + +An account balance is the net total of the amounts on any packets "successfully" routed between the peers. When a node sends an ILP Prepare packet to a peer, and receives a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer decreases.When a node receives an ILP Prepare packet and returns a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer increases. + +## Bandwidth + +The limit, set by a router, to the total value of ILP packets an account can send during a given period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. + +## Clearing + +The transferring (transmitting, reconciling, and confirming) of funds from payer to payee, such that the payer's account is debited for the promised amount and the payee's account is credited for the equal amount. + +See also: [Settlement](#settlement) + +## Connector + +See instead: [Router](#router) + +## Cyclic Transaction + +A transaction where the destination account is the same account, on the same ledger, as the source account. This can be useful when rebalancing liquidity (to enable future payments), or when rebalancing stored value (to spread risk, or to take advantage of changing exchange rates). + +## Destination Account + +The account of the receiver whose address is included in the Interledger packet. Note that anyone can claim to have a certain Interledger address; address ownership is not enforced. + +## Destination Amount + +The amount to be received by the receiver. + +## Distributed Ledger + +A ledger that is operated by a group of entities and runs on multiple servers. This term is used somewhat interchangeably with "Blockchain" or "Decentralized Ledger". + +## Exchange Rate + +The price of one ledger's asset in terms of another ledger's asset. Routers may generate revenue from the difference in value between incoming and outgoing transfers. The exchange rate between source and destination is determined by the product of exchange rates at each hop. + +## Fulfillment + +A 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). + +## Hold + +Part of the sender's, router's, and/or receiver's account balance is put "on hold" to reserve that balance for a specific ILP payment and is temporarily unavailable for use in other payments. The money is on hold while the ILP transfer is in the prepared state. If the transfer is executed, the money is no longer on hold, and added to the balance of the receiver of the transfer. If the transfer is rejected, the money is no longer on hold either, but is instead returned to the balance of the sender of the transfer. + +## Hop + +The movement of an ILP packet from one router to another as it travels through the Interledger network to reach its destination. + +## IL-RFC + +Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. + +## Incoming (Transfer, Ledger, Amount) + +The transfer/ledger/amount relative to the participant who plays the 'receiver' role. + +See also: [Outgoing](#outgoing-transfer-ledger-amount) + +## Interledger (in "Let's use Interledger for that!") + +The Interledger protocol stack. + +## interledger (in "An interledger network") + +A network of two or more ledgers that use the Interledger protocol stack. + +See also: [Interledger (The)](#interledger-in-the-interledger) + +The adjective 'interledger' is also sometimes used to refer to transactions that cross multiple ledgers, even if ILP is not used (similar to 'international' meaning 'across multiple nations'). + +## Interledger (in "The Interledger") + +The public network of ledgers connected via the Interledger protocol stack. + +## Interledger Address + +An Interledger address provides a way to route ILP packets to their intended destination through a series of hops, including any number of ILP routers. + +An Interledger address is a dot-separated string that contains prefixes to group ledgers. An example address might look like `g.us.acmebank.acmecorp.sales.199` or `g.crypto.bitcoin.1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2`. +Note that anyone can claim to have a certain Interledger address, there is no registry of them. Whether or not a payment ends up at the intended receiver is ultimately safeguarded by the hashlock condition, not by enforcement of address ownership. + +See also: [IL-RFC 15](https://github.com/interledger/rfcs/blob/master/0015-ilp-addresses/0015-ilp-addresses.md) + +## Interledger Architecture + +The Interledger protocol stack and the design principles behind it. + +## Interledger Layer + +The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts, routing, and whether each step in a payment arrives in time or expires. This protocol finds a path to connect a sender and receiver using any number of intermediaries. + +## Interledger Module + +The part of a software application that processes ILP payments. Analogous to the network card of an internet-connected computer. + +## Interledger Packet + +The binary data packet that is forwarded along all hops from sender to receiver. + +The packet includes metadata which the receiver may need before fulfilling the payment. It also includes metadata (such as destination account and amount) that routers use to determine what path to take. Alternatively, if the incoming amount is not large enough, compared to the destination amount in the ILP packet, the router may choose not to route the payment at all. + +ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly correspond to request, response, and error messages. + +## Interledger Protocol (ILP) + +The set of rules that define how Interledger nodes should communicate with each other. + +Colloquially, the whole Interledger stack is sometimes referred to as ILP. Technically, however, the Interledger Protocol is only one layer in the Interledger protocol stack. + +## Interledger Protocol Stack + +The stack consisting of the link layer, Interledger layer, a choice of transport layer protocols, and the application layer. + +## Intermediate (transfer, ledger, amount) + +Any transfer/ledger/amount that is neither directly adjacent to the sender nor the receiver. + +## Ledger + +Stateful systems that are used for clearing, settlement, and tracking the ownership of assets. Ledgers contain buckets of assets known as accounts and record transfers between them. Each account has a balance, which is the amount of the ledger's assets the account holds. Account balances may be positive or negative, representing assets or liabilities. + +## Link + +A communication path between two Interledger nodes to exchange ILP packets over an HTTPS or a WebSocket connection. + +## Node + +A node is a participant in the Interledger network. It can be a sender, router, or receiver, which has an accounting relationship with one or more participants. + +## Outgoing (Transfer, Ledger, Amount) + +The transfer/ledger/amount relative to the party who plays the sender role. + +See also: [Incoming](#incoming-transfer-ledger-amount) + +## Packetized Payment + +A large payment which is split into smaller packets that are then sent sequentially. Packetized payments reduce the total amount of money in-flight at a given time, which can reduce certain risks and costs. + +## Payment + +In the context of ILPv4, a payment is understood to mean the transfer of value from the sender (payer) to the receiver (payee). Higher-level protocols may execute a "payment" by sending a series of ILP Packets whose sum is equal to the desired payment value. + +## Payment Channel + +A payment channel is a medium used by two parties to perform multiple value transactions amongst them, without sending these transactions to the underlying ledger. One or both parties will generally transfer some of their value assets on the ledger to the payment channel. Value transfers are then made between the two parties by exchanging "claims" that update their balance. When one of the parties wishes to close the channel, they submit the final balance to the ledger. + +## Payment Pointer + +A payment pointer is a standardized identifier for accounts that can receive payments. It is like an email address, but for sending/receiving value. + +A payment pointer resolves to an HTTPS URL that provides the location of a payment setup service endpoint at which a sender can initiate a payment to the receiver. + +## Peer + +A router with which another router holds an account. + +## Peering + +Routers "peer" (establish an account) with one another to exchange information used to determine the best route for a payment, and to route it. This is similar to how internet service providers peer with each other (https://en.wikipedia.org/wiki/Peering). + +## Prepare Phase + +The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. Also, money is put on hold during this phase. + +## Prepared + +The state of a transfer in which the source account's funds are put on hold by the ledger until either the expiry is reached or the condition is fulfilled. + +## Receiver + +The Interledger node that is the final recipient of an Interledger payment. + +## Rejected + +A (final) transfer state whereby funds have been returned to the sender. + +## Route + +A set of transfers chained together by the routers between them. The route is the path a payment has taken, or a future payment could take. + +## Router + +An ILP router is similar to a network router on an IP network. Its primary function is to forward incoming packets between a sender and a receiver. + +A router may generate revenue from spreads on currency conversion, through subscription fees, or other means. + +## Routing Table + +A lookup table used by a router to decide who its outgoing receiver should be (the next hop, which can be another router or the destination receiver). + +## Sender + +The Interledger node that is the initiator (payer) of an Interledger payment. + +## Settlement + +The finalization of a payment, such that the payee takes the ownership of the transferred funds. + +## Simple Payment Setup Protocol (SPSP) + +An application layer protocol for exchanging payment information - destination account and secret - over HTTPS, between a payee and a payer, to facilitate payment over Interledger. + +SPSP uses the STREAM as transport layer protocol. + +See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) + +## Source (transfer, ledger, amount) + +The transfer/ledger/amount directly adjacent to the sender. + +## STREAM + +A Transport Protocol designed to be used with ILPv4. Application Layer protocols can use STREAM to send money and data between endpoints. + +## Streaming Payment + +An ongoing payment where small amounts of money are sent over time to pay for some ongoing service or rent. For instance, a user might pay for a streaming video with a streaming payment. The term "streaming payment" is commonly reserved for cases where the interval is short, from one second up to about a day. + +## Transaction + +See instead: [Payment](#payment) + +## Transfer + +The movement of assets from one peer to another. Multiple transfers can be chained together into one multi-hop payment. + +## Transport Layer + +The transport layer transports payment data between two parties, using the STREAM protocol. Transport Layer is the middle layer of the Interledger protocol stack, which determines the condition and encoding of the data in the ILP Packet. It also determines what details the sender and receiver need to discuss beforehand. + +## Value + +A financial asset that represents currency. It can be fiat (such as USD, EUR, JPY, etc.) or digital (such as BTC, ETH, XRP, etc.). From 670901827f6ef2b52dc64888e174f06edd38200c Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 11:06:36 -0700 Subject: [PATCH 02/20] add links --- docs/markdown/glossary.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index efa169a..9153ac3 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -112,7 +112,9 @@ See also: [IL-RFC 15](https://github.com/interledger/rfcs/blob/master/0015-ilp-a ## Interledger Architecture -The Interledger protocol stack and the design principles behind it. +The Interledger protocol stack and the design principles behind it. + +See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md) ## Interledger Layer @@ -134,7 +136,9 @@ ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly corres The set of rules that define how Interledger nodes should communicate with each other. -Colloquially, the whole Interledger stack is sometimes referred to as ILP. Technically, however, the Interledger Protocol is only one layer in the Interledger protocol stack. +Colloquially, the whole Interledger stack is sometimes referred to as ILP. Technically, however, the Interledger Protocol is only one layer in the Interledger protocol stack. + +See also: [IL-RFC 27](https://github.com/interledger/rfcs/blob/master/0027-interledger-protocol-4/0027-interledger-protocol-4.md) ## Interledger Protocol Stack @@ -178,7 +182,7 @@ A payment channel is a medium used by two parties to perform multiple value tran A payment pointer is a standardized identifier for accounts that can receive payments. It is like an email address, but for sending/receiving value. -A payment pointer resolves to an HTTPS URL that provides the location of a payment setup service endpoint at which a sender can initiate a payment to the receiver. +A payment pointer resolves to an HTTPS URL that provides the location of a payment setup service endpoint at which a sender can initiate a payment to the receiver. ## Peer @@ -256,7 +260,7 @@ The movement of assets from one peer to another. Multiple transfers can be chain ## Transport Layer -The transport layer transports payment data between two parties, using the STREAM protocol. Transport Layer is the middle layer of the Interledger protocol stack, which determines the condition and encoding of the data in the ILP Packet. It also determines what details the sender and receiver need to discuss beforehand. +The transport layer transports payment data between two parties, using the [STREAM](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) protocol. Transport Layer is the middle layer of the Interledger protocol stack, which determines the condition and encoding of the data in the ILP Packet. It also determines what details the sender and receiver need to discuss beforehand. ## Value From d661e8e048693fbc901345468397897da5bf159e Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 11:13:25 -0700 Subject: [PATCH 03/20] add links --- docs/markdown/glossary.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 9153ac3..e696fb8 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -142,7 +142,11 @@ See also: [IL-RFC 27](https://github.com/interledger/rfcs/blob/master/0027-inter ## Interledger Protocol Stack -The stack consisting of the link layer, Interledger layer, a choice of transport layer protocols, and the application layer. +The stack consisting of the link layer, Interledger layer, a choice of transport layer protocols, and the application layer. + +## ILPv4 + +See instead: [Interledger Protocol](#interledger-protocol-ilp) ## Intermediate (transfer, ledger, amount) @@ -244,7 +248,9 @@ The transfer/ledger/amount directly adjacent to the sender. ## STREAM -A Transport Protocol designed to be used with ILPv4. Application Layer protocols can use STREAM to send money and data between endpoints. +A Transport Protocol designed to be used with ILPv4. Application Layer protocols can use STREAM to send money and data between endpoints. + +See also: [IL-RFC 29](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) ## Streaming Payment From 2c8bbfcdd75332c6ea6502b78b43656d6729a36e Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 12:54:10 -0700 Subject: [PATCH 04/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index e696fb8..f9d4ddf 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -27,7 +27,7 @@ Something you can own. Can be a physical and unique item, a quantity of a physic ## Balance -An account balance is the net total of the amounts on any packets "successfully" routed between the peers. When a node sends an ILP Prepare packet to a peer, and receives a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer decreases.When a node receives an ILP Prepare packet and returns a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer increases. +An account balance is the net total of the amounts on any packets "successfully" routed between the peers. When a node sends an ILP Prepare packet to a peer, and receives a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer decreases. When a node receives an ILP Prepare packet and returns a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer increases. ## Bandwidth From fdd60a89790dc2396fbbba9d53743fd6bce3bda6 Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 12:54:33 -0700 Subject: [PATCH 05/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index f9d4ddf..aee793d 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -31,7 +31,7 @@ An account balance is the net total of the amounts on any packets "successfully" ## Bandwidth -The limit, set by a router, to the total value of ILP packets an account can send during a given period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. +The limit, set by a router, to the total value of ILP packets an account can send during a given time period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. ## Clearing From 672f5fc8f476324b10396c752b95b78c135d5c1f Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 13:05:41 -0700 Subject: [PATCH 06/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index aee793d..c07bed5 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -126,7 +126,11 @@ The part of a software application that processes ILP payments. Analogous to the ## Interledger Packet -The binary data packet that is forwarded along all hops from sender to receiver. +Also known as the ILP Packet. + +This is the binary data packet that is routed across all hops from sender to receiver in all Interledger payments. ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly correspond to request, response, and error messages. + +The ILP Prepare packet contains the details of the Interledger transaction, including the destination ILP Address, the amount to be sent, an expiration timestamp, a Condition, and data for the receiver. The ILP Fulfill packet contains the Fulfillment and data from the receiver for the sender. The ILP Reject packet contains an error code and message, as well as the ILP Address of the node that produced the error. The packet includes metadata which the receiver may need before fulfilling the payment. It also includes metadata (such as destination account and amount) that routers use to determine what path to take. Alternatively, if the incoming amount is not large enough, compared to the destination amount in the ILP packet, the router may choose not to route the payment at all. From 9a8c7b206fb8d301cef7d21e15f4ea6c7cbe4def Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 13:07:20 -0700 Subject: [PATCH 07/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index c07bed5..873176e 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -160,6 +160,9 @@ Any transfer/ledger/amount that is neither directly adjacent to the sender nor t Stateful systems that are used for clearing, settlement, and tracking the ownership of assets. Ledgers contain buckets of assets known as accounts and record transfers between them. Each account has a balance, which is the amount of the ledger's assets the account holds. Account balances may be positive or negative, representing assets or liabilities. +In Interledger v1, all Interledger packets were sent through ledgers. In Interledger v4, ledgers are primarily used as Settlement Systems to settle Balances accrued between nodes. + + ## Link A communication path between two Interledger nodes to exchange ILP packets over an HTTPS or a WebSocket connection. From 4603311565e1f7bcc62c727a94eadb7b811bcd38 Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 13:12:03 -0700 Subject: [PATCH 08/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 873176e..301bf07 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -205,7 +205,7 @@ Routers "peer" (establish an account) with one another to exchange information u ## Prepare Phase -The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. Also, money is put on hold during this phase. +The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. ## Prepared From 6ce2358938a4479a40d5c5822e22b45adf527a32 Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 13:12:37 -0700 Subject: [PATCH 09/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 301bf07..6d7ad8e 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -181,6 +181,7 @@ See also: [Incoming](#incoming-transfer-ledger-amount) A large payment which is split into smaller packets that are then sent sequentially. Packetized payments reduce the total amount of money in-flight at a given time, which can reduce certain risks and costs. +See also: Streaming Payments ## Payment In the context of ILPv4, a payment is understood to mean the transfer of value from the sender (payer) to the receiver (payee). Higher-level protocols may execute a "payment" by sending a series of ILP Packets whose sum is equal to the desired payment value. From ac7492e1bc404d438e4229c9a6a72aadaac30858 Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 13:13:25 -0700 Subject: [PATCH 10/20] Update docs/markdown/glossary.md Co-Authored-By: Evan Schwartz --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 6d7ad8e..9892dae 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -198,7 +198,7 @@ A payment pointer resolves to an HTTPS URL that provides the location of a payme ## Peer -A router with which another router holds an account. +A router with which another router holds an account and exchanges routing information via the Interledger routing protocol. ## Peering From 1d4a0e3e5113a1b76a87658409697644c3bf4b68 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 13:34:46 -0700 Subject: [PATCH 11/20] remove outdated terms --- docs/markdown/glossary.md | 48 +++++---------------------------------- 1 file changed, 6 insertions(+), 42 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 9892dae..0bd69dd 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -67,23 +67,13 @@ The price of one ledger's asset in terms of another ledger's asset. Routers may A 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). -## Hold - -Part of the sender's, router's, and/or receiver's account balance is put "on hold" to reserve that balance for a specific ILP payment and is temporarily unavailable for use in other payments. The money is on hold while the ILP transfer is in the prepared state. If the transfer is executed, the money is no longer on hold, and added to the balance of the receiver of the transfer. If the transfer is rejected, the money is no longer on hold either, but is instead returned to the balance of the sender of the transfer. - ## Hop The movement of an ILP packet from one router to another as it travels through the Interledger network to reach its destination. ## IL-RFC -Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. - -## Incoming (Transfer, Ledger, Amount) - -The transfer/ledger/amount relative to the participant who plays the 'receiver' role. - -See also: [Outgoing](#outgoing-transfer-ledger-amount) +Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. ## Interledger (in "Let's use Interledger for that!") @@ -118,11 +108,7 @@ See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interl ## Interledger Layer -The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts, routing, and whether each step in a payment arrives in time or expires. This protocol finds a path to connect a sender and receiver using any number of intermediaries. - -## Interledger Module - -The part of a software application that processes ILP payments. Analogous to the network card of an internet-connected computer. +The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts, routing, and whether each step in a payment arrives in time or expires. This protocol finds a path to connect a sender and receiver using any number of intermediaries. ## Interledger Packet @@ -152,10 +138,6 @@ The stack consisting of the link layer, Interledger layer, a choice of transport See instead: [Interledger Protocol](#interledger-protocol-ilp) -## Intermediate (transfer, ledger, amount) - -Any transfer/ledger/amount that is neither directly adjacent to the sender nor the receiver. - ## Ledger Stateful systems that are used for clearing, settlement, and tracking the ownership of assets. Ledgers contain buckets of assets known as accounts and record transfers between them. Each account has a balance, which is the amount of the ledger's assets the account holds. Account balances may be positive or negative, representing assets or liabilities. @@ -169,13 +151,7 @@ A communication path between two Interledger nodes to exchange ILP packets over ## Node -A node is a participant in the Interledger network. It can be a sender, router, or receiver, which has an accounting relationship with one or more participants. - -## Outgoing (Transfer, Ledger, Amount) - -The transfer/ledger/amount relative to the party who plays the sender role. - -See also: [Incoming](#incoming-transfer-ledger-amount) +A node is a participant in the Interledger network. It can be a sender, router, or receiver, which has an accounting relationship with one or more participants. ## Packetized Payment @@ -206,11 +182,7 @@ Routers "peer" (establish an account) with one another to exchange information u ## Prepare Phase -The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. - -## Prepared - -The state of a transfer in which the source account's funds are put on hold by the ledger until either the expiry is reached or the condition is fulfilled. +The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. ## Receiver @@ -248,11 +220,7 @@ An application layer protocol for exchanging payment information - destination a SPSP uses the STREAM as transport layer protocol. -See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) - -## Source (transfer, ledger, amount) - -The transfer/ledger/amount directly adjacent to the sender. +See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) ## STREAM @@ -266,11 +234,7 @@ An ongoing payment where small amounts of money are sent over time to pay for so ## Transaction -See instead: [Payment](#payment) - -## Transfer - -The movement of assets from one peer to another. Multiple transfers can be chained together into one multi-hop payment. +See instead: [Payment](#payment) ## Transport Layer From 82c6a7fceb86e49df3ce249f42465da0a1ff230f Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 15:02:33 -0700 Subject: [PATCH 12/20] update glossary --- docs/markdown/glossary.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 0bd69dd..2d02213 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -4,8 +4,7 @@ This glossary provides definitions for key terms in the Interledger ecosystem. ## Account -An accounting relationship between two Interledger participants. -In Interledger, two participants establish an account with one another to track the current obligations they hold with one another. +An accounting relationship between two Interledger participants. In Interledger, two participants establish an account with one another to track the current obligations they hold with one another. ## Address @@ -45,7 +44,7 @@ See instead: [Router](#router) ## Cyclic Transaction -A transaction where the destination account is the same account, on the same ledger, as the source account. This can be useful when rebalancing liquidity (to enable future payments), or when rebalancing stored value (to spread risk, or to take advantage of changing exchange rates). +A transaction where the destination account is the same account on the ledger as the source account. This can be useful when rebalancing liquidity (to enable future payments), or when rebalancing stored value (to spread risk, or to take advantage of changing exchange rates). ## Destination Account @@ -53,7 +52,7 @@ The account of the receiver whose address is included in the Interledger packet. ## Destination Amount -The amount to be received by the receiver. +The amount to be received by the receiver through ILP. ## Distributed Ledger @@ -61,11 +60,11 @@ A ledger that is operated by a group of entities and runs on multiple servers. T ## Exchange Rate -The price of one ledger's asset in terms of another ledger's asset. Routers may generate revenue from the difference in value between incoming and outgoing transfers. The exchange rate between source and destination is determined by the product of exchange rates at each hop. +The price of one ledger's asset in terms of another ledger's asset. Routers may generate revenue from the difference in value between incoming and outgoing transfers. The exchange rate between a sender and a receiver is determined by the product of exchange rates at each hop. ## Fulfillment -A 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). +Also known as the "preimage" or "hash preimage", fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). ## Hop @@ -96,6 +95,8 @@ The public network of ledgers connected via the Interledger protocol stack. An Interledger address provides a way to route ILP packets to their intended destination through a series of hops, including any number of ILP routers. An Interledger address is a dot-separated string that contains prefixes to group ledgers. An example address might look like `g.us.acmebank.acmecorp.sales.199` or `g.crypto.bitcoin.1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2`. + + Note that anyone can claim to have a certain Interledger address, there is no registry of them. Whether or not a payment ends up at the intended receiver is ultimately safeguarded by the hashlock condition, not by enforcement of address ownership. See also: [IL-RFC 15](https://github.com/interledger/rfcs/blob/master/0015-ilp-addresses/0015-ilp-addresses.md) @@ -140,14 +141,18 @@ See instead: [Interledger Protocol](#interledger-protocol-ilp) ## Ledger -Stateful systems that are used for clearing, settlement, and tracking the ownership of assets. Ledgers contain buckets of assets known as accounts and record transfers between them. Each account has a balance, which is the amount of the ledger's assets the account holds. Account balances may be positive or negative, representing assets or liabilities. +Stateful systems that are used for settlement and tracking the ownership of assets. Ledgers contain buckets of assets known as accounts and record transfers between them. Each account has a balance, which is the amount of the ledger's assets the account holds. Account balances may be positive or negative, representing assets or liabilities. In Interledger v1, all Interledger packets were sent through ledgers. In Interledger v4, ledgers are primarily used as Settlement Systems to settle Balances accrued between nodes. ## Link -A communication path between two Interledger nodes to exchange ILP packets over an HTTPS or a WebSocket connection. +A communication path between two Interledger nodes to exchange ILP packets over an HTTPS or a WebSocket connection. + +## Money Bandwidth + +See instead: [Bandwidth](#bandwidth) ## Node @@ -162,6 +167,10 @@ See also: Streaming Payments In the context of ILPv4, a payment is understood to mean the transfer of value from the sender (payer) to the receiver (payee). Higher-level protocols may execute a "payment" by sending a series of ILP Packets whose sum is equal to the desired payment value. +## Payment Bandwidth + +See instead: [Bandwidth](#bandwidth) + ## Payment Channel A payment channel is a medium used by two parties to perform multiple value transactions amongst them, without sending these transactions to the underlying ledger. One or both parties will generally transfer some of their value assets on the ledger to the payment channel. Value transfers are then made between the two parties by exchanging "claims" that update their balance. When one of the parties wishes to close the channel, they submit the final balance to the ledger. @@ -170,7 +179,11 @@ A payment channel is a medium used by two parties to perform multiple value tran A payment pointer is a standardized identifier for accounts that can receive payments. It is like an email address, but for sending/receiving value. -A payment pointer resolves to an HTTPS URL that provides the location of a payment setup service endpoint at which a sender can initiate a payment to the receiver. +A payment pointer resolves to an HTTPS URL that provides the location of a payment setup service endpoint at which a sender can initiate a payment to the receiver. + +For example, a pointer pointer such as `$example.com/bob` will resolve to `https://example.com/bob` endpoint URL. + +See also: [IL-RFC 26](https://github.com/interledger/rfcs/blob/master/0026-payment-pointers/0026-payment-pointers.md) ## Peer @@ -194,7 +207,7 @@ A (final) transfer state whereby funds have been returned to the sender. ## Route -A set of transfers chained together by the routers between them. The route is the path a payment has taken, or a future payment could take. +The path a payment has taken or a future payment could take. ## Router From 234a7cd87678ee6eec8cd48ea140d1386753c5ff Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 15:33:57 -0700 Subject: [PATCH 13/20] update glossary --- docs/markdown/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 2d02213..71ac683 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -52,7 +52,7 @@ The account of the receiver whose address is included in the Interledger packet. ## Destination Amount -The amount to be received by the receiver through ILP. +The amount to be received by the receiver through [ILP](#interledger-protocol-ilp). ## Distributed Ledger @@ -64,7 +64,7 @@ The price of one ledger's asset in terms of another ledger's asset. Routers may ## Fulfillment -Also known as the "preimage" or "hash preimage", fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). +Also known as the "preimage" or "hash preimage", a fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). ## Hop From f71cb4e29a3e3155a957835ad301772e4033d148 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 15:39:21 -0700 Subject: [PATCH 14/20] update glossary --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 71ac683..fc12f4d 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -48,7 +48,7 @@ A transaction where the destination account is the same account on the ledger as ## Destination Account -The account of the receiver whose address is included in the Interledger packet. Note that anyone can claim to have a certain Interledger address; address ownership is not enforced. +The account of the receiver whose address is included in the Interledger packet. ## Destination Amount From f806ecdd60ed1922e159d1a7ce263190e4d3f533 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 9 Sep 2019 16:06:10 -0700 Subject: [PATCH 15/20] add link --- docs/markdown/glossary.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index fc12f4d..15d645c 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -111,6 +111,8 @@ See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interl The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts, routing, and whether each step in a payment arrives in time or expires. This protocol finds a path to connect a sender and receiver using any number of intermediaries. +See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#interledger-protocol) + ## Interledger Packet Also known as the ILP Packet. From 1e2d622254a0862494a6f5932846429fef7b1f10 Mon Sep 17 00:00:00 2001 From: pgarg-ripple <51800920+pgarg-ripple@users.noreply.github.com> Date: Mon, 9 Sep 2019 16:47:00 -0700 Subject: [PATCH 16/20] Update docs/markdown/glossary.md Co-Authored-By: David Fuelling --- docs/markdown/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 15d645c..ebadd51 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -22,7 +22,7 @@ The practice of doing cyclic transactions which start and end on the same ledger ## Asset -Something you can own. Can be a physical and unique item, a quantity of a physical substance, a specific physical collection of coins and banknotes, a non-physical quantity of currency, a non-physical claim to a resource, a reputation for keeping one's word, someone else's intention to obey the terms of a contract, etc. Some types of assets can be more easily traded on a ledger than others. Also, for some asset pairs it is easier to determine a fair exchange rate than for others. +Something you can own that is fungible. Can be a physical item; a quantity of a physical substance; a specific physical collection of coins or banknotes; a non-physical quantity of currency; a non-physical claim to a resource; a reputation for keeping one's word; someone else's intention to obey the terms of a contract; etc. Some types of assets can be more easily traded on a ledger than others. For some asset pairs it is easier to determine a fair exchange rate than for others. ## Balance From f730643c866b8742ace1da32c1daaf66a79da308 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Sat, 14 Sep 2019 15:03:05 -0700 Subject: [PATCH 17/20] update definitions and add more links --- docs/markdown/glossary.md | 62 ++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 36 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index ebadd51..7245b06 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -4,7 +4,7 @@ This glossary provides definitions for key terms in the Interledger ecosystem. ## Account -An accounting relationship between two Interledger participants. In Interledger, two participants establish an account with one another to track the current obligations they hold with one another. +An accounting relationship between two Interledger participants. In Interledger, two participants establish an account with one another to track the current obligations they hold with one another. An Interledger account has a [balance](#balance) denominated in a mutually agreed upon asset (e.g. USD) at an agreed upon scale (e.g. 2). ## Address @@ -12,29 +12,28 @@ See instead: [Interledger Address](#interledger-address) ## Application Layer -The set of protocols built upon the Transport Layer that communicate payment details between senders and receivers. - -Application Layer protocols specify all of the data and methods required to set up a payment for a specific category of use cases or applications. For example, the Simple Payment Setup Protocol uses WebFinger and HTTPS for account detail lookup. +The set of protocols built upon the [Transport Layer](#transport-layer) that communicate payment details between [senders](#sender) and [receivers](#receiver). +Application Layer protocols specify all of the data and methods required to set up a payment for a specific category of use cases or applications. For example, the [Simple Payment Setup Protocol](#simple-payment-setup-protocol-spsp) uses HTTPS for account detail lookup. ## Arbitrage -The practice of doing cyclic transactions which start and end on the same ledger, or groups of simultaneous transactions which add up to one cyclic transaction. The goal is to achieve a destination amount which is higher than the source amount by taking advantage of fluctuations in exchange rates. +The practice of doing [cyclic transactions](#cyclic-transaction) which start and end on the same currency, or groups of simultaneous transactions which add up to one cyclic transaction. The goal is to achieve a destination amount which is higher than the source amount by taking advantage of fluctuations in exchange rates. ## Asset -Something you can own that is fungible. Can be a physical item; a quantity of a physical substance; a specific physical collection of coins or banknotes; a non-physical quantity of currency; a non-physical claim to a resource; a reputation for keeping one's word; someone else's intention to obey the terms of a contract; etc. Some types of assets can be more easily traded on a ledger than others. For some asset pairs it is easier to determine a fair exchange rate than for others. +Something you can own that is fungible. Can be a physical item; a quantity of a physical substance; a specific physical collection of coins or banknotes; a non-physical quantity of currency; a non-physical claim to a resource; a reputation for keeping one's word; someone else's intention to obey the terms of a contract; etc. ## Balance -An account balance is the net total of the amounts on any packets "successfully" routed between the peers. When a node sends an ILP Prepare packet to a peer, and receives a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer decreases. When a node receives an ILP Prepare packet and returns a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer increases. +An account balance is the net total of the amounts on any packets "successfully" routed between the peers. When a [node](#node) sends an ILP [Prepare packet](#interledger-packet) to a [peer](#peer), and receives a valid ILP [Fulfill](#interledger-packet) response, before the expiry of the ILP Prepare, their balance with that peer decreases, meaning the nodes owes the peer money. When a node receives an ILP Prepare packet and returns a valid ILP Fulfill response, before the expiry of the ILP Prepare, their balance with that peer increases, meaning the peer owes the node money. ## Bandwidth -The limit, set by a router, to the total value of ILP packets an account can send during a given time period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. +The limit, set by a [router](#router), to the total value of ILP packets an account can send during a given time period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. ## Clearing -The transferring (transmitting, reconciling, and confirming) of funds from payer to payee, such that the payer's account is debited for the promised amount and the payee's account is credited for the equal amount. +The transferring (transmitting, reconciling, and confirming) of funds from payer to payee, such that the payer's account is debited for the promised amount and the payee's account is credited for the equal amount. In Interledger this would involve the two peers exchanging data on what their current balance is and, if there is a discrepancy, resolving this. See also: [Settlement](#settlement) @@ -44,15 +43,14 @@ See instead: [Router](#router) ## Cyclic Transaction -A transaction where the destination account is the same account on the ledger as the source account. This can be useful when rebalancing liquidity (to enable future payments), or when rebalancing stored value (to spread risk, or to take advantage of changing exchange rates). +A transaction that is sent out from some sender's account and is received to another one of the sender's accounts. This can be useful when rebalancing liquidity (to enable future payments), or when rebalancing stored value (to spread risk, or to take advantage of changing exchange rates). ## Destination Account The account of the receiver whose address is included in the Interledger packet. - ## Destination Amount -The amount to be received by the receiver through [ILP](#interledger-protocol-ilp). +The amount the receiver ends up receiving through [ILP](#interledger-protocol-ilp). The destination amount maybe different from the amount that the sender sends because each router, participating in the transaction, may apply their exchange rate and adjust the amount. ## Distributed Ledger @@ -61,19 +59,21 @@ A ledger that is operated by a group of entities and runs on multiple servers. T ## Exchange Rate The price of one ledger's asset in terms of another ledger's asset. Routers may generate revenue from the difference in value between incoming and outgoing transfers. The exchange rate between a sender and a receiver is determined by the product of exchange rates at each hop. +## Expiry + +The date and time when the [Prepare packet](#interledger-packet) expires. Each router changes the value of this field to set the expiry to an earlier time, before forwarding the packet. ## Fulfillment -Also known as the "preimage" or "hash preimage", a fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). +Also known as the "preimage" or "hash preimage", a fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). +See also: [Conditions and Fulfillments](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#conditions-and-fulfillments) ## Hop -The movement of an ILP packet from one router to another as it travels through the Interledger network to reach its destination. - +A colloquial term for the manner in which value can move between two peers in the network. [ILP packets](#interledger-packet) travel from one router "hop" to another as they make their way through the Interledger network. ## IL-RFC Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. - ## Interledger (in "Let's use Interledger for that!") The Interledger protocol stack. @@ -100,16 +100,14 @@ An Interledger address is a dot-separated string that contains prefixes to group Note that anyone can claim to have a certain Interledger address, there is no registry of them. Whether or not a payment ends up at the intended receiver is ultimately safeguarded by the hashlock condition, not by enforcement of address ownership. See also: [IL-RFC 15](https://github.com/interledger/rfcs/blob/master/0015-ilp-addresses/0015-ilp-addresses.md) - ## Interledger Architecture The Interledger protocol stack and the design principles behind it. See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md) - ## Interledger Layer -The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts, routing, and whether each step in a payment arrives in time or expires. This protocol finds a path to connect a sender and receiver using any number of intermediaries. +The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts and whether each step in a payment arrives in time or expires. This protocol layer finds a path to connect a sender and receiver using any number of intermediaries. See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#interledger-protocol) @@ -121,9 +119,7 @@ This is the binary data packet that is routed across all hops from sender to rec The ILP Prepare packet contains the details of the Interledger transaction, including the destination ILP Address, the amount to be sent, an expiration timestamp, a Condition, and data for the receiver. The ILP Fulfill packet contains the Fulfillment and data from the receiver for the sender. The ILP Reject packet contains an error code and message, as well as the ILP Address of the node that produced the error. -The packet includes metadata which the receiver may need before fulfilling the payment. It also includes metadata (such as destination account and amount) that routers use to determine what path to take. Alternatively, if the incoming amount is not large enough, compared to the destination amount in the ILP packet, the router may choose not to route the payment at all. - -ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly correspond to request, response, and error messages. +The packet includes metadata which the receiver may need before fulfilling the payment. It also includes metadata (such as destination account and amount) that routers use to determine what path to take. Alternatively, if the incoming amount is not large enough, compared to the destination amount in the ILP packet, the router may choose not to route the payment at all. ## Interledger Protocol (ILP) @@ -132,7 +128,6 @@ The set of rules that define how Interledger nodes should communicate with each Colloquially, the whole Interledger stack is sometimes referred to as ILP. Technically, however, the Interledger Protocol is only one layer in the Interledger protocol stack. See also: [IL-RFC 27](https://github.com/interledger/rfcs/blob/master/0027-interledger-protocol-4/0027-interledger-protocol-4.md) - ## Interledger Protocol Stack The stack consisting of the link layer, Interledger layer, a choice of transport layer protocols, and the application layer. @@ -147,7 +142,6 @@ Stateful systems that are used for settlement and tracking the ownership of asse In Interledger v1, all Interledger packets were sent through ledgers. In Interledger v4, ledgers are primarily used as Settlement Systems to settle Balances accrued between nodes. - ## Link A communication path between two Interledger nodes to exchange ILP packets over an HTTPS or a WebSocket connection. @@ -165,10 +159,10 @@ A node is a participant in the Interledger network. It can be a sender, router, A large payment which is split into smaller packets that are then sent sequentially. Packetized payments reduce the total amount of money in-flight at a given time, which can reduce certain risks and costs. See also: Streaming Payments + ## Payment In the context of ILPv4, a payment is understood to mean the transfer of value from the sender (payer) to the receiver (payee). Higher-level protocols may execute a "payment" by sending a series of ILP Packets whose sum is equal to the desired payment value. - ## Payment Bandwidth See instead: [Bandwidth](#bandwidth) @@ -185,20 +179,18 @@ A payment pointer resolves to an HTTPS URL that provides the location of a payme For example, a pointer pointer such as `$example.com/bob` will resolve to `https://example.com/bob` endpoint URL. -See also: [IL-RFC 26](https://github.com/interledger/rfcs/blob/master/0026-payment-pointers/0026-payment-pointers.md) +See also: [IL-RFC 26](https://github.com/interledger/rfcs/blob/master/0026-payment-pointers/0026-payment-pointers.md) ## Peer A router with which another router holds an account and exchanges routing information via the Interledger routing protocol. - ## Peering Routers "peer" (establish an account) with one another to exchange information used to determine the best route for a payment, and to route it. This is similar to how internet service providers peer with each other (https://en.wikipedia.org/wiki/Peering). - ## Prepare Phase -The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. - +The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. + ## Receiver The Interledger node that is the final recipient of an Interledger payment. @@ -215,8 +207,8 @@ The path a payment has taken or a future payment could take. An ILP router is similar to a network router on an IP network. Its primary function is to forward incoming packets between a sender and a receiver. -A router may generate revenue from spreads on currency conversion, through subscription fees, or other means. - +A router may generate revenue from spreads on currency conversion, through subscription fees, or other means. + ## Routing Table A lookup table used by a router to decide who its outgoing receiver should be (the next hop, which can be another router or the destination receiver). @@ -227,7 +219,7 @@ The Interledger node that is the initiator (payer) of an Interledger payment. ## Settlement -The finalization of a payment, such that the payee takes the ownership of the transferred funds. +The finalization of a payment, such that the payee takes the ownership of the transferred funds. ## Simple Payment Setup Protocol (SPSP) @@ -236,12 +228,11 @@ An application layer protocol for exchanging payment information - destination a SPSP uses the STREAM as transport layer protocol. See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) - ## STREAM A Transport Protocol designed to be used with ILPv4. Application Layer protocols can use STREAM to send money and data between endpoints. -See also: [IL-RFC 29](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) +See also: [IL-RFC 29](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) ## Streaming Payment @@ -250,7 +241,6 @@ An ongoing payment where small amounts of money are sent over time to pay for so ## Transaction See instead: [Payment](#payment) - ## Transport Layer The transport layer transports payment data between two parties, using the [STREAM](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) protocol. Transport Layer is the middle layer of the Interledger protocol stack, which determines the condition and encoding of the data in the ILP Packet. It also determines what details the sender and receiver need to discuss beforehand. From c1e203e57e9080d57de2759130b85bd440ea7edf Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Wed, 18 Sep 2019 16:39:28 -0700 Subject: [PATCH 18/20] update more definitions --- docs/markdown/glossary.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 7245b06..7b18b37 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -15,6 +15,7 @@ See instead: [Interledger Address](#interledger-address) The set of protocols built upon the [Transport Layer](#transport-layer) that communicate payment details between [senders](#sender) and [receivers](#receiver). Application Layer protocols specify all of the data and methods required to set up a payment for a specific category of use cases or applications. For example, the [Simple Payment Setup Protocol](#simple-payment-setup-protocol-spsp) uses HTTPS for account detail lookup. + ## Arbitrage The practice of doing [cyclic transactions](#cyclic-transaction) which start and end on the same currency, or groups of simultaneous transactions which add up to one cyclic transaction. The goal is to achieve a destination amount which is higher than the source amount by taking advantage of fluctuations in exchange rates. @@ -48,6 +49,7 @@ A transaction that is sent out from some sender's account and is received to ano ## Destination Account The account of the receiver whose address is included in the Interledger packet. + ## Destination Amount The amount the receiver ends up receiving through [ILP](#interledger-protocol-ilp). The destination amount maybe different from the amount that the sender sends because each router, participating in the transaction, may apply their exchange rate and adjust the amount. @@ -59,6 +61,7 @@ A ledger that is operated by a group of entities and runs on multiple servers. T ## Exchange Rate The price of one ledger's asset in terms of another ledger's asset. Routers may generate revenue from the difference in value between incoming and outgoing transfers. The exchange rate between a sender and a receiver is determined by the product of exchange rates at each hop. + ## Expiry The date and time when the [Prepare packet](#interledger-packet) expires. Each router changes the value of this field to set the expiry to an earlier time, before forwarding the packet. @@ -85,7 +88,6 @@ A network of two or more ledgers that use the Interledger protocol stack. See also: [Interledger (The)](#interledger-in-the-interledger) The adjective 'interledger' is also sometimes used to refer to transactions that cross multiple ledgers, even if ILP is not used (similar to 'international' meaning 'across multiple nations'). - ## Interledger (in "The Interledger") The public network of ledgers connected via the Interledger protocol stack. @@ -94,17 +96,18 @@ The public network of ledgers connected via the Interledger protocol stack. An Interledger address provides a way to route ILP packets to their intended destination through a series of hops, including any number of ILP routers. -An Interledger address is a dot-separated string that contains prefixes to group ledgers. An example address might look like `g.us.acmebank.acmecorp.sales.199` or `g.crypto.bitcoin.1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2`. - +An Interledger address is a dot-separated string that is built up of segments which represent routers. An example address might look like `g.alice`, where `alice` would be the name of a router, or `g.alice.dave`, where `dave` is an account held with the router `alice`. Note that anyone can claim to have a certain Interledger address, there is no registry of them. Whether or not a payment ends up at the intended receiver is ultimately safeguarded by the hashlock condition, not by enforcement of address ownership. See also: [IL-RFC 15](https://github.com/interledger/rfcs/blob/master/0015-ilp-addresses/0015-ilp-addresses.md) + ## Interledger Architecture The Interledger protocol stack and the design principles behind it. See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md) + ## Interledger Layer The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts and whether each step in a payment arrives in time or expires. This protocol layer finds a path to connect a sender and receiver using any number of intermediaries. @@ -117,9 +120,7 @@ Also known as the ILP Packet. This is the binary data packet that is routed across all hops from sender to receiver in all Interledger payments. ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly correspond to request, response, and error messages. -The ILP Prepare packet contains the details of the Interledger transaction, including the destination ILP Address, the amount to be sent, an expiration timestamp, a Condition, and data for the receiver. The ILP Fulfill packet contains the Fulfillment and data from the receiver for the sender. The ILP Reject packet contains an error code and message, as well as the ILP Address of the node that produced the error. - -The packet includes metadata which the receiver may need before fulfilling the payment. It also includes metadata (such as destination account and amount) that routers use to determine what path to take. Alternatively, if the incoming amount is not large enough, compared to the destination amount in the ILP packet, the router may choose not to route the payment at all. +The ILP Prepare packet contains the details of the Interledger transaction, including the destination ILP Address, the amount to be sent, an expiration timestamp, a Condition, and data for the receiver. The ILP Fulfill packet contains the Fulfillment and data from the receiver for the sender. The ILP Reject packet contains an error code and message, as well as the ILP Address of the node that produced the error. ## Interledger Protocol (ILP) @@ -128,6 +129,7 @@ The set of rules that define how Interledger nodes should communicate with each Colloquially, the whole Interledger stack is sometimes referred to as ILP. Technically, however, the Interledger Protocol is only one layer in the Interledger protocol stack. See also: [IL-RFC 27](https://github.com/interledger/rfcs/blob/master/0027-interledger-protocol-4/0027-interledger-protocol-4.md) + ## Interledger Protocol Stack The stack consisting of the link layer, Interledger layer, a choice of transport layer protocols, and the application layer. @@ -157,12 +159,12 @@ A node is a participant in the Interledger network. It can be a sender, router, ## Packetized Payment A large payment which is split into smaller packets that are then sent sequentially. Packetized payments reduce the total amount of money in-flight at a given time, which can reduce certain risks and costs. - -See also: Streaming Payments +See also: [Streaming Payment](#streaming-payment) ## Payment In the context of ILPv4, a payment is understood to mean the transfer of value from the sender (payer) to the receiver (payee). Higher-level protocols may execute a "payment" by sending a series of ILP Packets whose sum is equal to the desired payment value. + ## Payment Bandwidth See instead: [Bandwidth](#bandwidth) @@ -170,7 +172,6 @@ See instead: [Bandwidth](#bandwidth) ## Payment Channel A payment channel is a medium used by two parties to perform multiple value transactions amongst them, without sending these transactions to the underlying ledger. One or both parties will generally transfer some of their value assets on the ledger to the payment channel. Value transfers are then made between the two parties by exchanging "claims" that update their balance. When one of the parties wishes to close the channel, they submit the final balance to the ledger. - ## Payment Pointer A payment pointer is a standardized identifier for accounts that can receive payments. It is like an email address, but for sending/receiving value. @@ -184,6 +185,7 @@ See also: [IL-RFC 26](https://github.com/interledger/rfcs/blob/master/0026-payme ## Peer A router with which another router holds an account and exchanges routing information via the Interledger routing protocol. + ## Peering Routers "peer" (establish an account) with one another to exchange information used to determine the best route for a payment, and to route it. This is similar to how internet service providers peer with each other (https://en.wikipedia.org/wiki/Peering). @@ -241,10 +243,7 @@ An ongoing payment where small amounts of money are sent over time to pay for so ## Transaction See instead: [Payment](#payment) + ## Transport Layer The transport layer transports payment data between two parties, using the [STREAM](https://github.com/interledger/rfcs/blob/master/0029-stream/0029-stream.md) protocol. Transport Layer is the middle layer of the Interledger protocol stack, which determines the condition and encoding of the data in the ILP Packet. It also determines what details the sender and receiver need to discuss beforehand. - -## Value - -A financial asset that represents currency. It can be fiat (such as USD, EUR, JPY, etc.) or digital (such as BTC, ETH, XRP, etc.). From 5a89962632869cffdd47e9936ba14a76609223f6 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Wed, 18 Sep 2019 17:02:00 -0700 Subject: [PATCH 19/20] fix space between headers --- docs/markdown/glossary.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 7b18b37..873f72b 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -73,10 +73,12 @@ See also: [Conditions and Fulfillments](https://github.com/interledger/rfcs/blob ## Hop -A colloquial term for the manner in which value can move between two peers in the network. [ILP packets](#interledger-packet) travel from one router "hop" to another as they make their way through the Interledger network. +A colloquial term for the manner in which value can move between two peers in the network. [ILP packets](#interledger-packet) travel from one router "hop" to another as they make their way through the Interledger network. + ## IL-RFC -Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. +Interledger request for comments. A document describing a part of the protocol stack, or a topic related to it, such as this glossary. The official list of IL-RFCs is maintained in gh:interledger/rfcs. + ## Interledger (in "Let's use Interledger for that!") The Interledger protocol stack. @@ -87,7 +89,8 @@ A network of two or more ledgers that use the Interledger protocol stack. See also: [Interledger (The)](#interledger-in-the-interledger) -The adjective 'interledger' is also sometimes used to refer to transactions that cross multiple ledgers, even if ILP is not used (similar to 'international' meaning 'across multiple nations'). +The adjective 'interledger' is also sometimes used to refer to transactions that cross multiple ledgers, even if ILP is not used (similar to 'international' meaning 'across multiple nations'). + ## Interledger (in "The Interledger") The public network of ledgers connected via the Interledger protocol stack. @@ -171,7 +174,8 @@ See instead: [Bandwidth](#bandwidth) ## Payment Channel -A payment channel is a medium used by two parties to perform multiple value transactions amongst them, without sending these transactions to the underlying ledger. One or both parties will generally transfer some of their value assets on the ledger to the payment channel. Value transfers are then made between the two parties by exchanging "claims" that update their balance. When one of the parties wishes to close the channel, they submit the final balance to the ledger. +A payment channel is a medium used by two parties to perform multiple value transactions amongst them, without sending these transactions to the underlying ledger. One or both parties will generally transfer some of their value assets on the ledger to the payment channel. Value transfers are then made between the two parties by exchanging "claims" that update their balance. When one of the parties wishes to close the channel, they submit the final balance to the ledger. + ## Payment Pointer A payment pointer is a standardized identifier for accounts that can receive payments. It is like an email address, but for sending/receiving value. @@ -188,7 +192,8 @@ A router with which another router holds an account and exchanges routing inform ## Peering -Routers "peer" (establish an account) with one another to exchange information used to determine the best route for a payment, and to route it. This is similar to how internet service providers peer with each other (https://en.wikipedia.org/wiki/Peering). +Routers "peer" (establish an account) with one another to exchange information used to determine the best route for a payment, and to route it. This is similar to how the internet service providers peer with each other (https://en.wikipedia.org/wiki/Peering). + ## Prepare Phase The first phase of an ILP payment, in which the ILP packet is passed from the sender, via the router(s), to the receiver. This represents an intent to pay, so long as the Fulfillment is delivered before the expiry. @@ -229,7 +234,8 @@ An application layer protocol for exchanging payment information - destination a SPSP uses the STREAM as transport layer protocol. -See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) +See also: [IL-RFC 9](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md) + ## STREAM A Transport Protocol designed to be used with ILPv4. Application Layer protocols can use STREAM to send money and data between endpoints. From d406825923bcca6dfb7a5c3362092efc11dabc52 Mon Sep 17 00:00:00 2001 From: Prachi Garg Date: Mon, 23 Sep 2019 12:28:53 -0700 Subject: [PATCH 20/20] update bandwidth definition --- docs/markdown/glossary.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/markdown/glossary.md b/docs/markdown/glossary.md index 873f72b..cbca14a 100644 --- a/docs/markdown/glossary.md +++ b/docs/markdown/glossary.md @@ -30,7 +30,7 @@ An account balance is the net total of the amounts on any packets "successfully" ## Bandwidth -The limit, set by a [router](#router), to the total value of ILP packets an account can send during a given time period. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's bandwidth with its peers. +The limit, set by a [router](#router), of the total value an account can have pending, or "in-flight" at any given moment in time. The limit may either be based on how much the router trusts the account-holder, or it may be used to prevent one account from tying up all of the router's liquidity with its peers. ## Clearing @@ -69,7 +69,8 @@ The date and time when the [Prepare packet](#interledger-packet) expires. Each r ## Fulfillment Also known as the "preimage" or "hash preimage", a fulfillment is a 32-byte value used to trigger the execution of a transfer. In most Interledger payments, the fulfillment is known only to the receiver (or in the case of the STREAM protocol it is known to the sender and the receiver). -See also: [Conditions and Fulfillments](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#conditions-and-fulfillments) + +See also: [Conditions and Fulfillments](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#conditions-and-fulfillments) ## Hop @@ -113,7 +114,7 @@ See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interl ## Interledger Layer -The second layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts and whether each step in a payment arrives in time or expires. This protocol layer finds a path to connect a sender and receiver using any number of intermediaries. +The layer of the Interledger protocol stack, consisting of the Interledger Protocol version 4 (ILPv4). This layer is concerned with currency amounts and whether each step in a payment arrives in time or expires. This protocol layer finds a path to connect a sender and receiver using any number of intermediaries. See also: [IL-RFC 1](https://github.com/interledger/rfcs/blob/master/0001-interledger-architecture/0001-interledger-architecture.md#interledger-protocol) @@ -218,7 +219,7 @@ A router may generate revenue from spreads on currency conversion, through subsc ## Routing Table -A lookup table used by a router to decide who its outgoing receiver should be (the next hop, which can be another router or the destination receiver). +A lookup table used by a router to decide who its outgoing receiver should be (the next hop, which can be another router or the destination receiver). ## Sender