Messages (including header) are signed by the sender's node key.
A requirement is that these messages can be used after the fact to prove a node's actions, in case there is a disagreement.
Messages to a particular node may be sent directly to that node's host if it is known, or encrypted and relayed across the trust network.
Header for all messages
- protocol version
- message type
- to (optional)
- eg, 1BteW1uy7zNXMNqhFdvFafbJLd1HcHVPLx, or 1BteW1uy7zNXMNqhFdvFafbJLd1HcHVPLx@ripplepay.com
- to_alias (optional)
- used instead of 'to' when correct node address is not known
- eg, ryan@ripplepay.com
- from
- from_key
- full key for validating message signature
- from_alias (optional)
- for responses to messages with 'to_alias', 'from' provides actual node address, 'from_alias' references the value of 'to_alias' that received the original message
- note that a server can use an alias to refer to more than one actual node address, depending on who's asking
- time (UTC)
Relay
(node to node)
For relaying an encrypted message on to another node. The only way to pass a message to a node whose host is not known. Might also be useful for deceiving traffic analyzers by routing through several other nodes when communicating with nodes whose host may be known.
- destination node
- may be bare address or address@host
- encrypted message (including header)
- may be another relay message containing another encrypted message, allowing onion routing, obscuring the ultimate destination.
Credit Offer
(account initiator to potential partner)
For initializing a line of credit, which is one direction/half of a mutual credit account between two nodes. Used to specify node addresses for aliases, units, arbiters for who is responsible for stalled commit messages, proving node owner identity, and linking two lines of credit together into a mutual credit account.
May also be used to inform an existing partner when a node has changed hosts: it can glean the new host from the 'from' address in the header.
Credit amounts are determined later, with credit advertisements.
- line of credit (LoC) ID
- linked LoC ID (optional)
- allows two lines of credit in opposite directions to have a linked balance and form a mutual credit account (lines of credit need not be between same node addresses)
- units
- list of acceptable commit message arbiter public keys (optional)
- note (optional)
- proof of owner identity (optional)
Credit Accept
(partner to account initiator)
- LoC ID
- linked LoC ID (optional)
- credit amount accepted
- units
- list of acceptable commit message arbiter keys (optional)
- note (optional)
- proof of owner identity (optional)
Credit
(broadcast)
Routing advertisements. Can be bundled together for transmission.
- source node(s)
- list of offers and accepts to and from other nodes
- partner node
- LoC ID
- amount
- exchange rate to/from node base unit
- may be number or reference to broadcast exchange rate ID (see below)
- valid until (number only)
- maybe allow node to indicate that it uses a common broadcast exchange rate, but modified by a fixed amount?
- flat fee on through transactions, in node base units
- requested hop limit for privacy? (optional)
- node hostname (+ port) (optional)
- allows other nodes to contact this node's host directly.
Exchange Rate
(broadcast)
Exchange rate advertisement. Allows frequent updates for common exchange rates that may be used by multiple nodes on multiple hosts across the network. Using common exchange rates means less update traffic.
- rate ID
- public key which signs the rate update messages
- numeric exchange rate (multiplier for unit conversion)
- valid until
Credit Check
(potential payer to recipient, and then back through flow network; or just payer to any intermediary with response directly back)
For getting up-to-date credit availability and fee information before initiating payment, either from an entire payment flow network, or from a single node.
- routing
- allows payer to request most recent credit information for a flow network he is interested in using.
- onion-routed flow network
- set of edges, with paths forking and merging
- key to encrypt each node's response
- list of node responses, in order
- each is a credit message body, encrypted with the checker's key
- may be padded with bogus responses at the start to disguise true number of intermediaries
Payment Init
(payer to recipient)
Inform recipient of an intended payment. This message gets signed by recipient and passed right back.
Units are not included, since they don't add anything to proving a payment of a certain amount was made. For example, a seller says "pay 30 to node X". The payer will be able to prove she did that. If the seller says "pay 30 CAD to node X", the payer won't be able to prove anything about node X's valuation or use of CAD, so the units are meaningless to the protocol (but might be useful for the payer to know about how much she will have to send out).
- transaction ID
- amount (to be received at recipient node, in node base units)
- memo
Payment Accept
(recipient to payer)
Gives payer a recipient-signed copy of payment amount tied to transaction ID, which, combined with signed commit message, proves payment occurred.
- copy of payment_init message
- recipient commit key
- proof of recipient node owner identity (optional)
- commit message URL (optional)
- location commit message will be publicly available when it is ready
Promise
(from payer, forward through flow network)
A promise to pass forward IOUs when shown a commit message signed by the payer and recipient commit keys before the expiry datetime (or when shown a commit message timestamped before the expiry by an acceptable arbiter). Acts as a credit reservation.
- transaction ID
- LoC ID
- amount to go forward
- expiry datetime
- payer commit key
- recipient commit key
- commit message URL
- list of acceptable commit message arbiter keys
- if at any time a commit message is presented signed by any of these keys, and timestamped before promise expiry, the promisor must pass IOUs forward as per promise.
- presumably the arbiter will publish these somewhere the promisor knows where to find them.
- if all arbiter keys are unacceptable, promise should be rejected with promise_release
- routing onion
- flow network: sets of edges, with paths forking and merging
- amount to go forward at each edge
- exchange rate at each edge/node
- nodes where merging happens should know to expect it so they can wait for it and perform merge before forwarding promise
Commit Ready
(recipient to payer)
The recipient has received sufficient promises and is ready to commit the transaction.
Promise Release
(recipient or intermediary to predecessor)
Release promisor from its promise.
Commit
(from recipient, back through flow network; also broadcast)
Trigger promises.
- transaction ID
- payer commit signature
- recipient commit signature
IOU
(payer or intermediary to successor)
Affirms that IOUs were issued. May be used outside a transaction in order to simply pass IOUs to an account partner (an act that needs no permission, fees, or available credit).
- transaction ID (optional)
- list of:
- LoC ID
- amount committed on LoC
Status Query
(payer to any intermediary or recipient)
Requests information about the current state of the transaction as seen by another participant.
- transaction ID
- signed by payer commit key
Status
(intermediary or recipient to payer)
Response to status query.
- transaction ID
- one or more status values:
- unknown transaction ID
- waiting for promise (only received some promises of expected promises to be merged)
- promise received
- promise rejected
- promise released
- promise expired
- commit received
- IOU received (is this any of the payer's business?)