DOCSEARCHbyAlgolia
Submit Docs

Interledger RFCs

repository·main·Indexed 19 days ago

https://github.com/interledger/rfcs

A collection of RFCs and technical specifications for the Interledger Protocol (ILP), providing foundational standards for cross-ledger payment routing and settlement. It includes specifications for the core ILPv4 protocol, ILP addresses, the STREAM transport layer, the Simple Payment Setup Protocol (SPSP), and settlement engine interfaces. The documentation also covers the Interledger architecture model, ASN.1 and Octet Encoding Rules (OER) for data structures, and test vectors for implementation verification.

Tokens
51.8K
Snippets
45
Records
148
Agent score
67%

What's inside interledger-rfcs

  1. Overview of Interledger HTTP Authentication Profiles

    main

    Interledger HTTP Authentication Profiles provide a minimal set of extensible, token-based profiles designed to secure Interledger relationships over HTTP. These profiles are intended for use in protocols like ILP-over-HTTP and for administrative functions within Interledger software.

    The profiles are designed to balance security and performance by:

    • Defining clear trade-offs for different security levels.
    • Ensuring ease of implementation across various programming languages.
    • Utilizing well-known, broadly deployed protocols.
    • Supporting high-performance use-cases (e.g., ILPv4 packet processing).
    • Resisting replay attacks (while acknowledging the performance trade-offs).
    • Allowing operators to layer additional security on top of the defined profiles.

  2. Overview of Interledger Protocol V4 (ILPv4)

    main

    Interledger Protocol V4 (ILPv4) is a protocol designed for transmitting packets of money across diverse payment networks or ledgers. It is specifically optimized for 'penny switching'—the routing of large volumes of low-value packets.

    Key characteristics include:

    • Simplification: It is a simplified version of previous ILP iterations.
    • Ledger Agnostic: It can be integrated with any ledger type, including those not originally designed for interoperability.
    • Extensibility: It is designed to work alongside higher-level protocols that handle features like quoting or chunked payments for larger value transfers.

  3. Access Interledger Protocol specifications and documentation

    main

    This repository serves as a central collection of specifications, Requests for Comment (RFCs), and documentation for the Interledger Protocol (ILP). It is organized into several functional layers: ASN.1 definitions, architectural overviews, core protocol specifications, application-layer protocols built on ILP, and ledger layer interfaces.

    Note that documents published here may not have official status unless explicitly stated within the document itself. For the primary reference implementation of the ILP stack, use Interledger.js.

  4. What is STREAM and how does it work?

    main

    STREAM (Streaming Transport for the Real-time Exchange of Assets and Messages) is a multiplexed Interledger Transport protocol designed to reliably send money and data over ILP. It establishes a virtual connection between a Client (the initiator) and a Server (the acceptor) using a Shared Secret to authenticate and encrypt packets.

    Key features include:

    • Multiplexing: Multiple logical, bi-directional Streams can run over a single connection.
    • Bi-directional Communication: Both endpoints can act as senders or receivers.
    • Flow Control: Supports both stream-level and connection-level flow control to manage the rate of money and data.
    • Reliability: Uses ILP Fulfill packets as acknowledgements (ACKs) for frames within a Prepare packet. If frames are rejected, an ILP Reject packet is used.
    • Security: Uses a shared secret to derive keys for encryption and to generate/fulfill ILP packet conditions.

  5. Overview of ILP Over HTTP

    main

    ILP Over HTTP is a bilateral communication protocol designed for server-to-server connections. It allows Interledger Protocol (ILP) packets to be transported over standard HTTP/HTTPS, enabling service providers to use existing infrastructure like load balancers, DDoS protection, and monitoring tools.

    In this model, both peers run HTTP servers. Peers exchange URLs, authentication credentials (tokens or TLS certificates), ILP addresses, and settlement details. ILP Prepare packets are sent as HTTP request bodies, and the recipient responds asynchronously with ILP Fulfill or Reject packets via separate HTTP requests.

  7. What is the Bilateral Transfer Protocol (BTP/2.0)?

    main
    BTP/2.0 is a request/response protocol designed for bilateral WebSocket links between Interledger connectors. Unlike HTTP POST, which requires both parties to act as servers, BTP uses WebSockets so that only one connector needs to be publicly addressable. It provides a request/response layer on top of WebSockets to correlate responses to requests using a Request ID.

  8. What is the Interledger Dynamic Configuration Protocol (ILDCP)?

    main

    The Interledger Dynamic Configuration Protocol (ILDCP) is used to transfer node and ledger configuration information from a parent node to a child node in a hierarchical Interledger network.

    This protocol allows a child node to receive the following configuration parameters from its parent:

    • ILP Address: The address the child should use (e.g., g.crypto.foo.bar).
    • Asset Code: The asset used for settlement between the two nodes (e.g., XRP).
    • Asset Scale: The scale for amounts used in ILP packets exchanged between the nodes (e.g., 6).

    ILDCP is essential for efficient routing, as it allows child nodes to be allocated addresses within their parent's address space.

  9. Understand alternative Hashed-Timelock Agreement (HTLA) types

    main

    Beyond standard HTLAs, several alternative models exist depending on the capabilities of the underlying ledger and the level of trust between parties. These include Third Party Escrow, Notarized Payment Channels, and Third Party Payment Channels.

    Third Party Escrow

    Used when a ledger supports fast, inexpensive transfers but lacks native support for holds.

    • Mechanism: The sender sends funds to an escrow provider along with a hashlock and timeout.
    • Execution: If the recipient submits the hashlock preimage before the timeout, the provider transfers funds to the recipient. Otherwise, funds return to the sender.
    • Trust Model: Both sender and recipient must trust the escrow provider for the full value of the transfer.

    Notarized Payment Channels

    Used to mitigate timeout disputes in payment channels caused by clock skew or network delays.

    • Mechanism: A third-party notary acts as a timekeeper. The recipient submits the preimage to the notary, who enforces the timeout.
    • Execution: The notary signs a statement attesting whether the preimage was received in time. This signed message is provided to both parties.
    • Trust Model: Parties must trust the notary not to collude or sign conflicting statements.

    Third Party Payment Channels

    An intermediate model between Escrow and Notarized Channels.

    • Mechanism: The sender funds a temporary account (similar to a Simple Payment Channel), but a third party's key is authorized to create claims on the channel balance instead of the sender's.
    • Execution: The recipient submits the preimage to the third party. If received before the timeout, the third party signs a new claim to pay the recipient from the sender's funds.
    • Trust Model: The recipient trusts the third party to enforce timeouts honestly. The sender trusts the third party not to create claims exceeding the amount owed (though collusion between the third party and recipient is a risk).

  10. Encrypt STREAM packets using AES-256-GCM

    main

    All STREAM packets are encrypted using AES-256-GCM with a 12-byte Initialization Vector (IV) and a 16-byte Authentication Tag. The encryption key for every packet in a connection is the HMAC-SHA256 digest of the shared secret and the string "ilp_stream_encryption" (UTF-8/ASCII).

    Security Constraints:

    • Nonce Uniqueness: Endpoints MUST NOT encrypt two packets with the same nonce (IV).
    • Connection Limits: Implementations MUST close the connection once either endpoint has sent $2^{31}$ packets to avoid unsafe AES-GCM usage.
    • Error Handling: If a receiver cannot decrypt a packet (e.g., due to an unsupported cipher), it SHOULD reject the transfer with an F06: Unexpected Payment error.
    var iv = random_bytes(12);
var encryption_key = hmac_sha256(shared_secret, "ilp_stream_encryption");
var { ciphertext, auth_tag } = aes_256_gcm(encryption_key, iv, data);

  11. Implement stream-level and connection-level flow control

    main

    STREAM uses a credit-based flow control scheme to limit incoming money and data.

    Stream-Level Flow Control

    Endpoints advertise limits for individual streams:

    • StreamMaxMoney: Maximum amount of money the endpoint is willing to receive.
    • StreamMaxData: Maximum number of bytes the endpoint is willing to receive.

    Rules:

    • Endpoints MAY increase limits by sending new frames with larger offsets.
    • Endpoints MUST NOT decrease limits (they MUST NOT advertise a smaller value later).
    • Senders MUST ignore flow control offsets that do not increase the window.
    • If a sender violates these limits, the receiver MUST close the connection with a FlowControlError.
    • Senders SHOULD emit StreamMoneyBlocked or StreamDataBlocked frames for debugging when limits are exceeded.

    Connection-Level Flow Control

    Endpoints can also limit total incoming data across all streams using ConnectionMaxData frames. Violating these limits also results in a FlowControlError.

  12. How StreamMoney frames allocate funds

    main

    The StreamMoney frame uses a Shares field to determine how much of the ILP Prepare amount is destined for a specific stream. The amount for a stream is calculated by dividing its shares by the total number of shares in all StreamMoney frames in the packet.

    Example Calculation:

    • ILP Prepare amount: 100
    • Frame 1 (Stream 2): 5 shares
    • Frame 2 (Stream 4): 15 shares
    • Frame 3 (Stream 6): 30 shares
    • Total Shares: 50
    • Stream 2 gets: (5/50) * 100 = 10 units
    • Stream 4 gets: (15/50) * 100 = 30 units
    • Stream 6 gets: (30/50) * 100 = 60 units

    Rounding: If the amount is not perfectly divisible, implementations SHOULD round stream amounts down. The remainder SHOULD be allocated to the lowest-numbered open stream that has not reached its maximum receive amount.

    | Field | Type | Description |
| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------