Protocol /
Payment
Protocol.Payment History
Hide minor edits - Show changes to output
May 18, 2007, at 05:39 PM
by - removed account stuff
Changed lines 9-23 from:
!!! Neighbour Connections
Ripple nodes may connect when one or both accept the other's obligations as valuable. Connected nodes are said to be neighbours. A ''neighbour connection'' is a relationship defined by an agreement to participate in Ripple transactions as neighbours, and does not refer tothe messaging connection that may exist from time to time between the neighbouring nodes' hosts, and over which the neighbour relationship takes place.
The Ripple Payment Protocol involves nodes issuing and accepting obligations of a certain value to and from their neighbours, but doesn't specify how these obligations are recorded or what the terms or limits of these obligations are. Neighbours must agree on an accounting system that will approve potential transactions and record the balance of committed transactions between them. One such system is the Ripple Account Protocol.
A neighbour connection consists of nothing other than one or more accounts between the neighbours. The minimal set of data that must be known by two neighbouring nodes in order to participate in Ripple payments is:
* a Ripple ID for each node
* an account ID
* the unit of account
* an authentication key for each node
The JSON data structure for an account is:
Ripple nodes may connect when one or both accept the other's obligations as valuable. Connected nodes are said to be neighbours. A ''neighbour connection'' is a relationship defined by an agreement to participate in Ripple transactions as neighbours, and does not refer to
The Ripple Payment Protocol involves nodes issuing and accepting obligations of a certain value to and from their neighbours, but doesn't specify how these obligations are recorded or what the terms or limits of these obligations are. Neighbours must agree on an accounting system that will approve potential transactions and record the balance of committed transactions between them. One such system is the Ripple Account Protocol.
A neighbour connection consists of nothing other than one or more accounts between the neighbours. The minimal set of data that must be known by two neighbouring nodes in order to participate in Ripple payments is:
* a Ripple ID for each node
* an account ID
* the unit of account
* an authentication key for each node
The JSON data structure for an account is:
to:
!!! Payments
To allow payments between two nodes that aren't neighbours, Ripple propagates value account-by-account along one or more paths of accounts in the network connecting payer and recipient.
The basic payment process consists of:
# Initializing payment between the payer and recipient nodes
# Preparing the paths to commit the transaction
# Committing the transaction
[[#requesting-payment]]
'''Requesting Payment'''
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to that node containing:
* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* an explanatory note
To allow payments between two nodes that aren't neighbours, Ripple propagates value account-by-account along one or more paths of accounts in the network connecting payer and recipient.
The basic payment process consists of:
# Initializing payment between the payer and recipient nodes
# Preparing the paths to commit the transaction
# Committing the transaction
[[#requesting-payment]]
'''Requesting Payment'''
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to that node containing:
* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* an explanatory note
Changed lines 32-44 from:
"key": (public key data structure)
},
"partner": {
"node-id": (Ripple ID),
"key": (public key data structure)
},
to:
"payment-request": {
"payment-id": (string),
"amount": (decimal),
"unit": (URI),
"recipient-node-id": (Ripple ID),
"note": (string)
}
"payment-id": (string),
"amount": (decimal),
"unit": (URI),
"recipient-node-id": (Ripple ID),
"note": (string)
}
Changed lines 42-52 from:
The roles of @@initiator@@ node and @@partner@@ node are determined at account creation time, with the node making the initial account offer being deemed the @@initiator@@. These roles stay constant for the life of the account, allowing either node to change its node ID.
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> Account]] or another electronic accounts system.
[[#account-messages]]
'''Account Messages'''
There are two primary account messages: @@account-request@@ and @@account-set@@.
An @@account-request@@ is to request a new account, or to request a change to one or more account fields that could not be dictated unilaterally by the requesting node. An @@account-request@@ must be signed unless the request could in other circumstances be imposed unilaterally by the node receiving the request. Otherwise, the requesting node must indicate that it gives permission to make the requested changes by signing the @@account-request@@, which allows this permission to be verified at a later date. If a node receives an unsigned message that it feels ought to be signed, it should reply with a ''Message must be signed'' error. An implementation may decide to simply sign every @@account-request@@.
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> Account]] or another electronic accounts system.
[[#account-messages]]
'''Account Messages'''
There are two primary account messages: @@account-request@@ and @@account-set@@.
An @@account-request@@ is to request a new account, or
to:
The @@payment-request@@ may be followed by an @@payment-init@@ message from the potential payer, or ignored.
The @@payment-request@@ message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios where the buyer is unable to communicate directly with his or her node. (Ideally, the smart card would display the payment amount and units to the buyer for approval, otherwise he or she must trust that the seller's terminal displays the same amount as it is asking the smart card to authorize in the @@payment-request@@ message.)
[[#initializing-payment]]
'''Initializing Payment'''
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
* unique ID for the payment
* amount to be paid to recipient
* units of payment
* some explanatory text to the recipient
The @@payment-request@@ message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios where the buyer is unable to communicate directly with his or her node. (Ideally, the smart card would display the payment amount and units to the buyer for approval, otherwise he or she must trust that the seller's terminal displays the same amount as it is asking the smart card to authorize in the @@payment-request@@ message.)
[[#initializing-payment]]
'''Initializing Payment'''
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
* unique ID for the payment
* amount to be paid to recipient
* units of payment
* some explanatory text to the recipient
Changed lines 58-68 from:
"
"
"body": {
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
("note": (string))
to:
"payment-init": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string)
}
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string)
}
Changed lines 67-72 from:
The
An @@account-set@@ must always be signed.
to:
When generating @@payment-id@@s, nodes should make every effort to ensure they are globally unique in the Ripple network, although this is not strictly necessary for the system to function. Since the @@payment-id@@ field may be an arbitrary string, this shouldn't be too difficult by following a convention such as appending the precise date & time (UTC) to each ID.
The recipient may accept the @@payment-init@@ with an affirmative reply containing a @@payment-accept@@ message with the following data:
* payment ID
* amount to be paid to recipient
* units of payment
* payer's explanatory text echoed back
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer
The recipient may accept the @@payment-init@@ with an affirmative reply containing a @@payment-accept@@ message with the following data:
* payment ID
* amount to be paid to recipient
* units of payment
* payer's explanatory text echoed back
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer
Changed lines 80-90 from:
"
"
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
to:
"payment-accept": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string),
"recipient-receipt-key": (public key data structure),
"recipient-certificate": (certificate data structure)
}
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string),
"recipient-receipt-key": (public key data structure),
"recipient-certificate": (certificate data structure)
}
Changed lines 91-107 from:
The timestamp establishes the exact time the changes to
Account messages, other than at account-creation time, should only alter one account field at a time unless two or more fields must be altered in atomic fashion
[[#establishing-an-account]]
'''Establishing an Account'''
Accounts are established by a signed @@account-request@@ message sent between potential or existing neighbours containing the basic information for the account:
* a request ID
* an account ID
*
* the units of
Example:
to:
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer. This message serves as evidence that the recipient participated in the transaction. Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received. The explanatory text can contain text linking the payment to a real-world exchange of goods or services, such as "Payment for auction item #12345".
The recipient may reject the @@payment-init@@ with an error code.
[[#making-promises]]
'''Making Promises (Commit-Request)'''
To prepare the payment paths, the payer sends a @@promise@@ message to the first node on each path, representing its commitment to redeem a valid receipt that can be authenticated with the promise's authentication key up to the amount of credit indicated on the receipt, if presented before the stated deadline.
* payment ID
* path ID
* amount to be held for payment, in path units
* ID of account to be made part of path by this promise being passed
* amount to be held for payment, in account units
* a routing onion (optional)
* a time limit to reach the recipient, in connection time
* promise penalty deadline, in connection time
* daily penalty rate if receipt or path-cancel not received before the penalty deadline
* promise final deadline, in connection time, after which promise expires
* the payer's receipt authentication key for this payment path
* the recipient's receipt authentication key for this payment path
* a timestamp to indicate the time the promise came into effect, in connection time
The recipient may reject the @@payment-init@@ with an error code.
[[#making-promises]]
'''Making Promises (Commit-Request)'''
To prepare the payment paths, the payer sends a @@promise@@ message to the first node on each path, representing its commitment to redeem a valid receipt that can be authenticated with the promise's authentication key up to the amount of credit indicated on the receipt, if presented before the stated deadline.
* payment ID
* path ID
* amount to be held for payment, in path units
* ID of account to be made part of path by this promise being passed
* amount to be held for payment, in account units
* a routing onion (optional)
* a time limit to reach the recipient, in connection time
* promise penalty deadline, in connection time
* daily penalty rate if receipt or path-cancel not received before the penalty deadline
* promise final deadline, in connection time, after which promise expires
* the payer's receipt authentication key for this payment path
* the recipient's receipt authentication key for this payment path
* a timestamp to indicate the time the promise came into effect, in connection time
Changed lines 116-135 from:
"from":
"
"initiator": {
"node-id": "rfugger@ripplepay.com",
"key": (...),
},
"partner": {
"node-id": "random@example.com",
}
},
"note": "Let's have an account!"
to:
"promise": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal),
"account-id": (string),
"amount": (decimal),
"onion": (routing onion data structure),
"ttl": (date/time string),
"penalty-deadline": (date/time string),
"penalty-rate": (decimal),
"deadline": (date/time string),
"payer-receipt-key": (public key data structure),
"recipient-receipt-key": (public key data structure),
"timestamp": (date/time string)
}
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal),
"account-id": (string),
"amount": (decimal),
"onion": (routing onion data structure),
"ttl": (date/time string),
"penalty-deadline": (date/time string),
"penalty-rate": (decimal),
"deadline": (date/time string),
"payer-receipt-key": (public key data structure),
"recipient-receipt-key": (public key data structure),
"timestamp": (date/time string)
}
Changed lines 134-178 from:
To indicate that the account has been created, the node receiving the @@account-set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#identification-of-account-partner]]
'''Identification of Account Partner'''
Ripple has no universal mechanism for positively identifying the owner of another node. The owner of a node receiving a new account request should confirm the identity of the owner of the requesting node before assigning it a non-zero credit limit. Even if the node ID in the form ''node@host.com'' of the requesting node is familiar to the request recipient, one must ensure that the transport layer has verified positively by some means that the request actually comes from the correct host and that the host is trustworthy before relying solely on that piece of information.
The requesting node's owner may put secret, personal, or other information that could help the receiving node's owner identify them, such as a message signed with a personal signing key, into the @@note@@ field of the @@account-request@@.
[[#changing-account-data]]
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account-set@@ message to its account partner. An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account-request@@ message. An affirmative reply here only indicates that the request has been understood and is being held for approval.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account-set@@ completes the change.
[[#account-change-errors]]
'''Account Change Errors'''
The following errors allow nodes to negotiate between them what are permissible unilateral changes and what aren't in case of disagreement:
: ''Field change by account-request only'' : Contains path to field that node receiving an @@account-set@@ deems requires an @@account-request@@ to change in the manner requested.
: ''Unilateral declaration preferred'' : Node receiving an @@account-request@@ deems an @@account-set@@ preferable for the requested change. (Equally valid is to simply accept the request immediately -- perhaps this error is unnecessary?)
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account-set@@ or @@account-request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
[[#changing-keys]]
'''Changing Keys'''
An account message declaring or requesting a key change should be signed by the old key. Subsequent signed messages must be signed by the new key.
[[#verifying-account-data]]
'''Verifying Account Data'''
To request a copy of an account partner's account data for verification, send an @@account-verify-request@@ message containing the account ID:
Example:
to:
Since a promise must be fulfilled if a valid @@receipt@@ is presented, it must effectively hold the required amount on the designated account in such a way that no other transaction may invalidate the payment.
Each node that receives a promise message updates its fields and passes it on to the next node in the path, as determined by data gleaned from the routing onion and/or by extension fields that inform a routing system defined in a protocol extension. At each step, the promise message is signed to the next node by the passing node's authentication key. This serves to establish the integrity and non-repudiability of the promise.
The @@path-id@@ is defined as an ordered list of strings to accommodate routing systems that may use such lists to permit paths to fork into multiple directions while still allowing previous intermediaries in the path to recognize these subpaths and prevent loops from forming. Therefore, a path with ID @@[ A, B ]@@ must be recognized as a forked continuation of the path the same @@payment-id@@ and @@path-id@@ @@[ A ]@@. For the purposes of @@promise@@ and @@receipt@@ routing, these are the same path.
The @@path-amount@@ is invented by the payer and given in arbitrary units (''path units'') particular to each path. This figure gives each intermediary a reference against which to know the value of the @@receipt@@ message that commits the transaction, which will contain a @@path-amount@@ less than or equal to the @@promise@@ @@path-amount@@.
The @@ttl@@ (''time-to-live'') field allows the payer to specify a deadline for the @@promise@@ to reach the recipient. If it should fail to reach the recipient by that time, the latest receiver of the @@promise@@ should release the sender from its promise, and so on back to the payer (see [[Releasing Promises -> #releasing-promises]] below). This field allows the payer to reasonably limit the amount of time it wishes to wait to see whether the path is viable.
The @@penalty-deadline@@ is the time after which the promising node may begin charging a penalty to its partner for having to hold credit it could be using for payment. The penalty is charged continuously at the daily rate specified. Intermediaries should always set a shorter deadline and higher penalty rate on promises out than they have received on promises in, to ensure that they are compensated for overdue @@receipts@@. This provides incentive for the recipient to ensure quick completion or cancellation of each promise path, without requiring hard-and-fast deadlines to come into play so soon that minor delays relaying the receipt back along the path spawn major disputes.
[[#finalizing-payment]]
'''Finalizing the Payment'''
As the recipient receives each @@promise@@, it reports it back to the payer with a @@promise-received@@:
* payment ID
* path ID
* recipient's deadline for accepting the receipts for these paths, in connection time
* final amount of promise in payment units as computed by recipient
Each node that receives a promise message updates its fields and passes it on to the next node in the path, as determined by data gleaned from the routing onion and/or by extension fields that inform a routing system defined in a protocol extension. At each step, the promise message is signed to the next node by the passing node's authentication key. This serves to establish the integrity and non-repudiability of the promise.
The @@path-id@@ is defined as an ordered list of strings to accommodate routing systems that may use such lists to permit paths to fork into multiple directions while still allowing previous intermediaries in the path to recognize these subpaths and prevent loops from forming. Therefore, a path with ID @@[ A, B ]@@ must be recognized as a forked continuation of the path the same @@payment-id@@ and @@path-id@@ @@[ A ]@@. For the purposes of @@promise@@ and @@receipt@@ routing, these are the same path.
The @@path-amount@@ is invented by the payer and given in arbitrary units (''path units'') particular to each path. This figure gives each intermediary a reference against which to know the value of the @@receipt@@ message that commits the transaction, which will contain a @@path-amount@@ less than or equal to the @@promise@@ @@path-amount@@.
The @@ttl@@ (''time-to-live'') field allows the payer to specify a deadline for the @@promise@@ to reach the recipient. If it should fail to reach the recipient by that time, the latest receiver of the @@promise@@ should release the sender from its promise, and so on back to the payer (see [[Releasing Promises -> #releasing-promises]] below). This field allows the payer to reasonably limit the amount of time it wishes to wait to see whether the path is viable.
The @@penalty-deadline@@ is the time after which the promising node may begin charging a penalty to its partner for having to hold credit it could be using for payment. The penalty is charged continuously at the daily rate specified. Intermediaries should always set a shorter deadline and higher penalty rate on promises out than they have received on promises in, to ensure that they are compensated for overdue @@receipts@@. This provides incentive for the recipient to ensure quick completion or cancellation of each promise path, without requiring hard-and-fast deadlines to come into play so soon that minor delays relaying the receipt back along the path spawn major disputes.
[[#finalizing-payment]]
'''Finalizing the Payment'''
As the recipient receives each @@promise@@, it reports it back to the payer with a @@promise-received@@:
* payment ID
* path ID
* recipient's deadline for accepting the receipts for these paths, in connection time
* final amount of promise in payment units as computed by recipient
Changed lines 158-159 from:
"account-verify-request": {
"account-id": "550e8400-e29b-41d4-a716-446655440000"
"
to:
"promise-received": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"deadline": (date/time string),
"amount": (decimal)
"payment-id": (string),
"path-id": [(ordered list of strings)],
"deadline": (date/time string),
"amount": (decimal)
Changed lines 167-169 from:
The immediate reply must contain the complete account data structure of the node receiving the @@account-verify-request@@ as well as a timestamp:
Example:
to:
The recipient's receipt deadline to the payer should be well before the penalty deadline on the @@promise@@ the recipient received.
The recipient can cancel the transaction at any time by sending the payer a @@payment-cancel@@ and releasing its neighbours from their promises with a @@promise-release@@ (see [[Releasing Promises -> #releasing-promises]]). The payer can cancel the transaction by sending the recipient a @@payment-cancel@@, informing it that it can release its neighbours from their promises. Released promises should be propagated back down each payment path to free up those funds for other payments.
When the payer receives a satisfactory set of @@promise-received@@ messages totaling the payment amount or greater, it generates one @@receipt@@ message per @@promise-received@@s, authenticates it individually with the corresponding @@payer-receipt-key@@, and sends it to the recipient before the deadline for doing so:
* payment ID
* path ID
* amount for this path, in path units
The recipient can cancel the transaction at any time by sending the payer a @@payment-cancel@@ and releasing its neighbours from their promises with a @@promise-release@@ (see [[Releasing Promises -> #releasing-promises]]). The payer can cancel the transaction by sending the recipient a @@payment-cancel@@, informing it that it can release its neighbours from their promises. Released promises should be propagated back down each payment path to free up those funds for other payments.
When the payer receives a satisfactory set of @@promise-received@@ messages totaling the payment amount or greater, it generates one @@receipt@@ message per @@promise-received@@s, authenticates it individually with the corresponding @@payer-receipt-key@@, and sends it to the recipient before the deadline for doing so:
* payment ID
* path ID
* amount for this path, in path units
Changed lines 179-183 from:
"account-verify": {
"timestamp": "2006-11-07 02:11:28.401000",
"account": {
(...)
}
"
to:
"receipt": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal)
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal)
Deleted lines 186-415:
[[#account-history]]
'''Account History'''
To request from an account partner a list of every signed message that has changed the value of an account field over a certain period, send an @@account-history-request@@:
Example:
[@
{
"account-history-request": {
"starting": "2006-01-01 00:00:00.000000",
"ending": "2006-11-07 02:11:28.401000"
}
}
@]
If the "starting" field is omitted, messages from beginning of the account should be included in the reply. If the "ending" field is omitted, messages up to the present should be included.
The reply is as follows:
[@
{
"account-history": [
(a chronological order of signed messages sent and received over
this account during the requested period that have changed a piece
of shared account data, in the format they were originally sent or
received, including signatures)
]
}
@]
This account history may be used as an audit to find the source of any data discrepancies between partners. This same output may also be taken for each account by a node owner from her own node in order to backup account data or move a node to a different host.
[[#closing-an-account]]
'''Closing an Account'''
To close an account, either party may send an @@account-close@@ message containing the ID of the account to be closed:
Example:
[@
{
"account-close": {
"request-id": 14590,
"account-id": "550e8400-e29b-41d4-a716-446655440000"
}
}
@]
An affirmative reply indicates assent to close the account. An error indicates refusal.
!!! Payments
To allow payments between two nodes that aren't neighbours, Ripple propagates value account-by-account along one or more paths of accounts in the network connecting payer and recipient.
The basic payment process consists of:
# Initializing payment between the payer and recipient nodes
# Preparing the paths to commit the transaction
# Committing the transaction
[[#requesting-payment]]
'''Requesting Payment'''
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to that node containing:
* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* an explanatory note
[@
{
"payment-request": {
"payment-id": (string),
"amount": (decimal),
"unit": (URI),
"recipient-node-id": (Ripple ID),
"note": (string)
}
}
@]
The @@payment-request@@ may be followed by an @@payment-init@@ message from the potential payer, or ignored.
The @@payment-request@@ message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios where the buyer is unable to communicate directly with his or her node. (Ideally, the smart card would display the payment amount and units to the buyer for approval, otherwise he or she must trust that the seller's terminal displays the same amount as it is asking the smart card to authorize in the @@payment-request@@ message.)
[[#initializing-payment]]
'''Initializing Payment'''
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
* unique ID for the payment
* amount to be paid to recipient
* units of payment
* some explanatory text to the recipient
[@
{
"payment-init": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string)
}
}
@]
When generating @@payment-id@@s, nodes should make every effort to ensure they are globally unique in the Ripple network, although this is not strictly necessary for the system to function. Since the @@payment-id@@ field may be an arbitrary string, this shouldn't be too difficult by following a convention such as appending the precise date & time (UTC) to each ID.
The recipient may accept the @@payment-init@@ with an affirmative reply containing a @@payment-accept@@ message with the following data:
* payment ID
* amount to be paid to recipient
* units of payment
* payer's explanatory text echoed back
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer
[@
{
"payment-accept": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string),
"recipient-receipt-key": (public key data structure),
"recipient-certificate": (certificate data structure)
}
}
@]
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer. This message serves as evidence that the recipient participated in the transaction. Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received. The explanatory text can contain text linking the payment to a real-world exchange of goods or services, such as "Payment for auction item #12345".
The recipient may reject the @@payment-init@@ with an error code.
[[#making-promises]]
'''Making Promises (Commit-Request)'''
To prepare the payment paths, the payer sends a @@promise@@ message to the first node on each path, representing its commitment to redeem a valid receipt that can be authenticated with the promise's authentication key up to the amount of credit indicated on the receipt, if presented before the stated deadline.
* payment ID
* path ID
* amount to be held for payment, in path units
* ID of account to be made part of path by this promise being passed
* amount to be held for payment, in account units
* a routing onion (optional)
* a time limit to reach the recipient, in connection time
* promise penalty deadline, in connection time
* daily penalty rate if receipt or path-cancel not received before the penalty deadline
* promise final deadline, in connection time, after which promise expires
* the payer's receipt authentication key for this payment path
* the recipient's receipt authentication key for this payment path
* a timestamp to indicate the time the promise came into effect, in connection time
[@
{
"promise": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal),
"account-id": (string),
"amount": (decimal),
"onion": (routing onion data structure),
"ttl": (date/time string),
"penalty-deadline": (date/time string),
"penalty-rate": (decimal),
"deadline": (date/time string),
"payer-receipt-key": (public key data structure),
"recipient-receipt-key": (public key data structure),
"timestamp": (date/time string)
}
}
@]
Since a promise must be fulfilled if a valid @@receipt@@ is presented, it must effectively hold the required amount on the designated account in such a way that no other transaction may invalidate the payment.
Each node that receives a promise message updates its fields and passes it on to the next node in the path, as determined by data gleaned from the routing onion and/or by extension fields that inform a routing system defined in a protocol extension. At each step, the promise message is signed to the next node by the passing node's authentication key. This serves to establish the integrity and non-repudiability of the promise.
The @@path-id@@ is defined as an ordered list of strings to accommodate routing systems that may use such lists to permit paths to fork into multiple directions while still allowing previous intermediaries in the path to recognize these subpaths and prevent loops from forming. Therefore, a path with ID @@[ A, B ]@@ must be recognized as a forked continuation of the path the same @@payment-id@@ and @@path-id@@ @@[ A ]@@. For the purposes of @@promise@@ and @@receipt@@ routing, these are the same path.
The @@path-amount@@ is invented by the payer and given in arbitrary units (''path units'') particular to each path. This figure gives each intermediary a reference against which to know the value of the @@receipt@@ message that commits the transaction, which will contain a @@path-amount@@ less than or equal to the @@promise@@ @@path-amount@@.
The @@ttl@@ (''time-to-live'') field allows the payer to specify a deadline for the @@promise@@ to reach the recipient. If it should fail to reach the recipient by that time, the latest receiver of the @@promise@@ should release the sender from its promise, and so on back to the payer (see [[Releasing Promises -> #releasing-promises]] below). This field allows the payer to reasonably limit the amount of time it wishes to wait to see whether the path is viable.
The @@penalty-deadline@@ is the time after which the promising node may begin charging a penalty to its partner for having to hold credit it could be using for payment. The penalty is charged continuously at the daily rate specified. Intermediaries should always set a shorter deadline and higher penalty rate on promises out than they have received on promises in, to ensure that they are compensated for overdue @@receipts@@. This provides incentive for the recipient to ensure quick completion or cancellation of each promise path, without requiring hard-and-fast deadlines to come into play so soon that minor delays relaying the receipt back along the path spawn major disputes.
[[#finalizing-payment]]
'''Finalizing the Payment'''
As the recipient receives each @@promise@@, it reports it back to the payer with a @@promise-received@@:
* payment ID
* path ID
* recipient's deadline for accepting the receipts for these paths, in connection time
* final amount of promise in payment units as computed by recipient
[@
{
"promise-received": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"deadline": (date/time string),
"amount": (decimal)
}
}
@]
The recipient's receipt deadline to the payer should be well before the penalty deadline on the @@promise@@ the recipient received.
The recipient can cancel the transaction at any time by sending the payer a @@payment-cancel@@ and releasing its neighbours from their promises with a @@promise-release@@ (see [[Releasing Promises -> #releasing-promises]]). The payer can cancel the transaction by sending the recipient a @@payment-cancel@@, informing it that it can release its neighbours from their promises. Released promises should be propagated back down each payment path to free up those funds for other payments.
When the payer receives a satisfactory set of @@promise-received@@ messages totaling the payment amount or greater, it generates one @@receipt@@ message per @@promise-received@@s, authenticates it individually with the corresponding @@payer-receipt-key@@, and sends it to the recipient before the deadline for doing so:
* payment ID
* path ID
* amount for this path, in path units
[@
{
"receipt": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal)
}
}
@]
Changed lines 44-45 from:
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> AccountExtension]] or another electronic accounts system.
to:
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> Account]] or another electronic accounts system.
Added lines 3-4:
''This page is a bit dated, but is still here for the descriptions of how the connection and payment processes work. The actual message fields are more accurately given on the [[work page -> PaymentWorkPage]].''
Added lines 1-430:
!!Ripple Payment Protocol
[[Protocol/Payment Work Page]]
!!! Neighbour Connections
Ripple nodes may connect when one or both accept the other's obligations as valuable. Connected nodes are said to be neighbours. A ''neighbour connection'' is a relationship defined by an agreement to participate in Ripple transactions as neighbours, and does not refer to the messaging connection that may exist from time to time between the neighbouring nodes' hosts, and over which the neighbour relationship takes place.
The Ripple Payment Protocol involves nodes issuing and accepting obligations of a certain value to and from their neighbours, but doesn't specify how these obligations are recorded or what the terms or limits of these obligations are. Neighbours must agree on an accounting system that will approve potential transactions and record the balance of committed transactions between them. One such system is the Ripple Account Protocol.
A neighbour connection consists of nothing other than one or more accounts between the neighbours. The minimal set of data that must be known by two neighbouring nodes in order to participate in Ripple payments is:
* a Ripple ID for each node
* an account ID
* the unit of account
* an authentication key for each node
The JSON data structure for an account is:
[@
{
"account": {
"account-id": (string),
"unit": (URI),
"external-id": (string),
"initiator": {
"node-id": (Ripple ID),
"key": (public key data structure)
},
"partner": {
"node-id": (Ripple ID),
"key": (public key data structure)
},
}
}
@]
The roles of @@initiator@@ node and @@partner@@ node are determined at account creation time, with the node making the initial account offer being deemed the @@initiator@@. These roles stay constant for the life of the account, allowing either node to change its node ID.
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> AccountExtension]] or another electronic accounts system.
[[#account-messages]]
'''Account Messages'''
There are two primary account messages: @@account-request@@ and @@account-set@@.
An @@account-request@@ is to request a new account, or to request a change to one or more account fields that could not be dictated unilaterally by the requesting node. An @@account-request@@ must be signed unless the request could in other circumstances be imposed unilaterally by the node receiving the request. Otherwise, the requesting node must indicate that it gives permission to make the requested changes by signing the @@account-request@@, which allows this permission to be verified at a later date. If a node receives an unsigned message that it feels ought to be signed, it should reply with a ''Message must be signed'' error. An implementation may decide to simply sign every @@account-request@@.
[@
{
"type": "account-request",
"to": (string),
"from": (string),
"request-id": (integer),
"body": {
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
("note": (string))
}
}
@]
To avoid overlap, the @@initiator@@ node uses odd request IDs, and the @@partner@@ node uses even request IDs. Only those account fields that contain new, non-default values, or are to be changed need to be included.
The @@account-set@@ message is to confirm a new account, accept the changes requested in an @@account-request@@, or to unilaterally declare changes to account fields where permitted. While any arrangement may be negotiated between nodes by trial and error, in general, a node may unilaterally dictate values for its own @@node-id@@, @@routing-id@@, and @@key@@, as well as decreases to either node's credit limit. Credit limit increases would generally require an @@account-request@@, although when it contains an increase to the other node's limit, the request is better understood as an offer.
An @@account-set@@ must always be signed.
[@
{
"type": "account-set",
"to": (string),
"from": (string),
("request-id": (integer),)
"time": (date/time string),
"body": {
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
}
}
@]
The @@request-id@@ is only necessary when the @@account-set@@ refers to an earlier request. In that case, the account fields must be identical to those in the earlier @@account-request@@ with the same request ID.
The timestamp establishes the exact time the changes to the account fields take effect.
Account messages, other than at account-creation time, should only alter one account field at a time unless two or more fields must be altered in atomic fashion.
[[#establishing-an-account]]
'''Establishing an Account'''
Accounts are established by a signed @@account-request@@ message sent between potential or existing neighbours containing the basic information for the account:
* a request ID
* an account ID
* the offering node's network ID
* the units of account
Example:
[@
{
"type": "account-request",
"to": "random",
"from": "rfugger",
"request-id": 1,
"time": "2007-04-01 15:53:41.537449",
"body": {
"account": {
"account-id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"external-id": "120489",
"initiator": {
"node-id": "rfugger@ripplepay.com",
"key": (...),
},
"partner": {
"node-id": "random@example.com",
}
},
"note": "Let's have an account!"
}
}
@]
An affirmative reply means the offer has been understood being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account-set@@ echoing the request ID and the full account data structure in the request, as well as a timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account-set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#identification-of-account-partner]]
'''Identification of Account Partner'''
Ripple has no universal mechanism for positively identifying the owner of another node. The owner of a node receiving a new account request should confirm the identity of the owner of the requesting node before assigning it a non-zero credit limit. Even if the node ID in the form ''node@host.com'' of the requesting node is familiar to the request recipient, one must ensure that the transport layer has verified positively by some means that the request actually comes from the correct host and that the host is trustworthy before relying solely on that piece of information.
The requesting node's owner may put secret, personal, or other information that could help the receiving node's owner identify them, such as a message signed with a personal signing key, into the @@note@@ field of the @@account-request@@.
[[#changing-account-data]]
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account-set@@ message to its account partner. An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account-request@@ message. An affirmative reply here only indicates that the request has been understood and is being held for approval.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account-set@@ completes the change.
[[#account-change-errors]]
'''Account Change Errors'''
The following errors allow nodes to negotiate between them what are permissible unilateral changes and what aren't in case of disagreement:
: ''Field change by account-request only'' : Contains path to field that node receiving an @@account-set@@ deems requires an @@account-request@@ to change in the manner requested.
: ''Unilateral declaration preferred'' : Node receiving an @@account-request@@ deems an @@account-set@@ preferable for the requested change. (Equally valid is to simply accept the request immediately -- perhaps this error is unnecessary?)
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account-set@@ or @@account-request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
[[#changing-keys]]
'''Changing Keys'''
An account message declaring or requesting a key change should be signed by the old key. Subsequent signed messages must be signed by the new key.
[[#verifying-account-data]]
'''Verifying Account Data'''
To request a copy of an account partner's account data for verification, send an @@account-verify-request@@ message containing the account ID:
Example:
[@
{
"account-verify-request": {
"account-id": "550e8400-e29b-41d4-a716-446655440000"
}
}
@]
The immediate reply must contain the complete account data structure of the node receiving the @@account-verify-request@@ as well as a timestamp:
Example:
[@
{
"account-verify": {
"timestamp": "2006-11-07 02:11:28.401000",
"account": {
(...)
}
}
}
@]
Neither message nor reply must be signed.
[[#account-history]]
'''Account History'''
To request from an account partner a list of every signed message that has changed the value of an account field over a certain period, send an @@account-history-request@@:
Example:
[@
{
"account-history-request": {
"starting": "2006-01-01 00:00:00.000000",
"ending": "2006-11-07 02:11:28.401000"
}
}
@]
If the "starting" field is omitted, messages from beginning of the account should be included in the reply. If the "ending" field is omitted, messages up to the present should be included.
The reply is as follows:
[@
{
"account-history": [
(a chronological order of signed messages sent and received over
this account during the requested period that have changed a piece
of shared account data, in the format they were originally sent or
received, including signatures)
]
}
@]
This account history may be used as an audit to find the source of any data discrepancies between partners. This same output may also be taken for each account by a node owner from her own node in order to backup account data or move a node to a different host.
[[#closing-an-account]]
'''Closing an Account'''
To close an account, either party may send an @@account-close@@ message containing the ID of the account to be closed:
Example:
[@
{
"account-close": {
"request-id": 14590,
"account-id": "550e8400-e29b-41d4-a716-446655440000"
}
}
@]
An affirmative reply indicates assent to close the account. An error indicates refusal.
!!! Payments
To allow payments between two nodes that aren't neighbours, Ripple propagates value account-by-account along one or more paths of accounts in the network connecting payer and recipient.
The basic payment process consists of:
# Initializing payment between the payer and recipient nodes
# Preparing the paths to commit the transaction
# Committing the transaction
[[#requesting-payment]]
'''Requesting Payment'''
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to that node containing:
* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* an explanatory note
[@
{
"payment-request": {
"payment-id": (string),
"amount": (decimal),
"unit": (URI),
"recipient-node-id": (Ripple ID),
"note": (string)
}
}
@]
The @@payment-request@@ may be followed by an @@payment-init@@ message from the potential payer, or ignored.
The @@payment-request@@ message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios where the buyer is unable to communicate directly with his or her node. (Ideally, the smart card would display the payment amount and units to the buyer for approval, otherwise he or she must trust that the seller's terminal displays the same amount as it is asking the smart card to authorize in the @@payment-request@@ message.)
[[#initializing-payment]]
'''Initializing Payment'''
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
* unique ID for the payment
* amount to be paid to recipient
* units of payment
* some explanatory text to the recipient
[@
{
"payment-init": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string)
}
}
@]
When generating @@payment-id@@s, nodes should make every effort to ensure they are globally unique in the Ripple network, although this is not strictly necessary for the system to function. Since the @@payment-id@@ field may be an arbitrary string, this shouldn't be too difficult by following a convention such as appending the precise date & time (UTC) to each ID.
The recipient may accept the @@payment-init@@ with an affirmative reply containing a @@payment-accept@@ message with the following data:
* payment ID
* amount to be paid to recipient
* units of payment
* payer's explanatory text echoed back
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer
[@
{
"payment-accept": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string),
"recipient-receipt-key": (public key data structure),
"recipient-certificate": (certificate data structure)
}
}
@]
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer. This message serves as evidence that the recipient participated in the transaction. Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received. The explanatory text can contain text linking the payment to a real-world exchange of goods or services, such as "Payment for auction item #12345".
The recipient may reject the @@payment-init@@ with an error code.
[[#making-promises]]
'''Making Promises (Commit-Request)'''
To prepare the payment paths, the payer sends a @@promise@@ message to the first node on each path, representing its commitment to redeem a valid receipt that can be authenticated with the promise's authentication key up to the amount of credit indicated on the receipt, if presented before the stated deadline.
* payment ID
* path ID
* amount to be held for payment, in path units
* ID of account to be made part of path by this promise being passed
* amount to be held for payment, in account units
* a routing onion (optional)
* a time limit to reach the recipient, in connection time
* promise penalty deadline, in connection time
* daily penalty rate if receipt or path-cancel not received before the penalty deadline
* promise final deadline, in connection time, after which promise expires
* the payer's receipt authentication key for this payment path
* the recipient's receipt authentication key for this payment path
* a timestamp to indicate the time the promise came into effect, in connection time
[@
{
"promise": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal),
"account-id": (string),
"amount": (decimal),
"onion": (routing onion data structure),
"ttl": (date/time string),
"penalty-deadline": (date/time string),
"penalty-rate": (decimal),
"deadline": (date/time string),
"payer-receipt-key": (public key data structure),
"recipient-receipt-key": (public key data structure),
"timestamp": (date/time string)
}
}
@]
Since a promise must be fulfilled if a valid @@receipt@@ is presented, it must effectively hold the required amount on the designated account in such a way that no other transaction may invalidate the payment.
Each node that receives a promise message updates its fields and passes it on to the next node in the path, as determined by data gleaned from the routing onion and/or by extension fields that inform a routing system defined in a protocol extension. At each step, the promise message is signed to the next node by the passing node's authentication key. This serves to establish the integrity and non-repudiability of the promise.
The @@path-id@@ is defined as an ordered list of strings to accommodate routing systems that may use such lists to permit paths to fork into multiple directions while still allowing previous intermediaries in the path to recognize these subpaths and prevent loops from forming. Therefore, a path with ID @@[ A, B ]@@ must be recognized as a forked continuation of the path the same @@payment-id@@ and @@path-id@@ @@[ A ]@@. For the purposes of @@promise@@ and @@receipt@@ routing, these are the same path.
The @@path-amount@@ is invented by the payer and given in arbitrary units (''path units'') particular to each path. This figure gives each intermediary a reference against which to know the value of the @@receipt@@ message that commits the transaction, which will contain a @@path-amount@@ less than or equal to the @@promise@@ @@path-amount@@.
The @@ttl@@ (''time-to-live'') field allows the payer to specify a deadline for the @@promise@@ to reach the recipient. If it should fail to reach the recipient by that time, the latest receiver of the @@promise@@ should release the sender from its promise, and so on back to the payer (see [[Releasing Promises -> #releasing-promises]] below). This field allows the payer to reasonably limit the amount of time it wishes to wait to see whether the path is viable.
The @@penalty-deadline@@ is the time after which the promising node may begin charging a penalty to its partner for having to hold credit it could be using for payment. The penalty is charged continuously at the daily rate specified. Intermediaries should always set a shorter deadline and higher penalty rate on promises out than they have received on promises in, to ensure that they are compensated for overdue @@receipts@@. This provides incentive for the recipient to ensure quick completion or cancellation of each promise path, without requiring hard-and-fast deadlines to come into play so soon that minor delays relaying the receipt back along the path spawn major disputes.
[[#finalizing-payment]]
'''Finalizing the Payment'''
As the recipient receives each @@promise@@, it reports it back to the payer with a @@promise-received@@:
* payment ID
* path ID
* recipient's deadline for accepting the receipts for these paths, in connection time
* final amount of promise in payment units as computed by recipient
[@
{
"promise-received": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"deadline": (date/time string),
"amount": (decimal)
}
}
@]
The recipient's receipt deadline to the payer should be well before the penalty deadline on the @@promise@@ the recipient received.
The recipient can cancel the transaction at any time by sending the payer a @@payment-cancel@@ and releasing its neighbours from their promises with a @@promise-release@@ (see [[Releasing Promises -> #releasing-promises]]). The payer can cancel the transaction by sending the recipient a @@payment-cancel@@, informing it that it can release its neighbours from their promises. Released promises should be propagated back down each payment path to free up those funds for other payments.
When the payer receives a satisfactory set of @@promise-received@@ messages totaling the payment amount or greater, it generates one @@receipt@@ message per @@promise-received@@s, authenticates it individually with the corresponding @@payer-receipt-key@@, and sends it to the recipient before the deadline for doing so:
* payment ID
* path ID
* amount for this path, in path units
[@
{
"receipt": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal)
}
}
@]
The collection of receipts signed by the payer represents the value of the payment, and once they are given to the recipient, the recipient is considered to have been paid. If any of the receipts is invalid (to be rigorously defined), the amount of that receipt is not considered to have been paid until a valid receipt is issued. The recipient must reply with an error code when receiving an invalid receipt.
The recipient redeems receipts with its neighbours that have issued promises to do so. Each receipt may only partially redeem the value of a single promise, and multiple receipts may be redeemed for a single promise. The unredeemed portion of the promise must be released before the penalty deadline or the penalty must be paid.
[[Protocol/Payment Work Page]]
[[Protocol/Payment Work Page]]
!!! Neighbour Connections
Ripple nodes may connect when one or both accept the other's obligations as valuable. Connected nodes are said to be neighbours. A ''neighbour connection'' is a relationship defined by an agreement to participate in Ripple transactions as neighbours, and does not refer to the messaging connection that may exist from time to time between the neighbouring nodes' hosts, and over which the neighbour relationship takes place.
The Ripple Payment Protocol involves nodes issuing and accepting obligations of a certain value to and from their neighbours, but doesn't specify how these obligations are recorded or what the terms or limits of these obligations are. Neighbours must agree on an accounting system that will approve potential transactions and record the balance of committed transactions between them. One such system is the Ripple Account Protocol.
A neighbour connection consists of nothing other than one or more accounts between the neighbours. The minimal set of data that must be known by two neighbouring nodes in order to participate in Ripple payments is:
* a Ripple ID for each node
* an account ID
* the unit of account
* an authentication key for each node
The JSON data structure for an account is:
[@
{
"account": {
"account-id": (string),
"unit": (URI),
"external-id": (string),
"initiator": {
"node-id": (Ripple ID),
"key": (public key data structure)
},
"partner": {
"node-id": (Ripple ID),
"key": (public key data structure)
},
}
}
@]
The roles of @@initiator@@ node and @@partner@@ node are determined at account creation time, with the node making the initial account offer being deemed the @@initiator@@. These roles stay constant for the life of the account, allowing either node to change its node ID.
The @@external-id@@ identifies the account to be used in the supporting accounting system, which may be [[Ripple mutual accounts -> AccountExtension]] or another electronic accounts system.
[[#account-messages]]
'''Account Messages'''
There are two primary account messages: @@account-request@@ and @@account-set@@.
An @@account-request@@ is to request a new account, or to request a change to one or more account fields that could not be dictated unilaterally by the requesting node. An @@account-request@@ must be signed unless the request could in other circumstances be imposed unilaterally by the node receiving the request. Otherwise, the requesting node must indicate that it gives permission to make the requested changes by signing the @@account-request@@, which allows this permission to be verified at a later date. If a node receives an unsigned message that it feels ought to be signed, it should reply with a ''Message must be signed'' error. An implementation may decide to simply sign every @@account-request@@.
[@
{
"type": "account-request",
"to": (string),
"from": (string),
"request-id": (integer),
"body": {
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
("note": (string))
}
}
@]
To avoid overlap, the @@initiator@@ node uses odd request IDs, and the @@partner@@ node uses even request IDs. Only those account fields that contain new, non-default values, or are to be changed need to be included.
The @@account-set@@ message is to confirm a new account, accept the changes requested in an @@account-request@@, or to unilaterally declare changes to account fields where permitted. While any arrangement may be negotiated between nodes by trial and error, in general, a node may unilaterally dictate values for its own @@node-id@@, @@routing-id@@, and @@key@@, as well as decreases to either node's credit limit. Credit limit increases would generally require an @@account-request@@, although when it contains an increase to the other node's limit, the request is better understood as an offer.
An @@account-set@@ must always be signed.
[@
{
"type": "account-set",
"to": (string),
"from": (string),
("request-id": (integer),)
"time": (date/time string),
"body": {
"account": {
"account-id": (string),
(remaining account data structure containing requested field values)
},
}
}
@]
The @@request-id@@ is only necessary when the @@account-set@@ refers to an earlier request. In that case, the account fields must be identical to those in the earlier @@account-request@@ with the same request ID.
The timestamp establishes the exact time the changes to the account fields take effect.
Account messages, other than at account-creation time, should only alter one account field at a time unless two or more fields must be altered in atomic fashion.
[[#establishing-an-account]]
'''Establishing an Account'''
Accounts are established by a signed @@account-request@@ message sent between potential or existing neighbours containing the basic information for the account:
* a request ID
* an account ID
* the offering node's network ID
* the units of account
Example:
[@
{
"type": "account-request",
"to": "random",
"from": "rfugger",
"request-id": 1,
"time": "2007-04-01 15:53:41.537449",
"body": {
"account": {
"account-id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"external-id": "120489",
"initiator": {
"node-id": "rfugger@ripplepay.com",
"key": (...),
},
"partner": {
"node-id": "random@example.com",
}
},
"note": "Let's have an account!"
}
}
@]
An affirmative reply means the offer has been understood being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account-set@@ echoing the request ID and the full account data structure in the request, as well as a timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account-set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#identification-of-account-partner]]
'''Identification of Account Partner'''
Ripple has no universal mechanism for positively identifying the owner of another node. The owner of a node receiving a new account request should confirm the identity of the owner of the requesting node before assigning it a non-zero credit limit. Even if the node ID in the form ''node@host.com'' of the requesting node is familiar to the request recipient, one must ensure that the transport layer has verified positively by some means that the request actually comes from the correct host and that the host is trustworthy before relying solely on that piece of information.
The requesting node's owner may put secret, personal, or other information that could help the receiving node's owner identify them, such as a message signed with a personal signing key, into the @@note@@ field of the @@account-request@@.
[[#changing-account-data]]
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account-set@@ message to its account partner. An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account-request@@ message. An affirmative reply here only indicates that the request has been understood and is being held for approval.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account-set@@ completes the change.
[[#account-change-errors]]
'''Account Change Errors'''
The following errors allow nodes to negotiate between them what are permissible unilateral changes and what aren't in case of disagreement:
: ''Field change by account-request only'' : Contains path to field that node receiving an @@account-set@@ deems requires an @@account-request@@ to change in the manner requested.
: ''Unilateral declaration preferred'' : Node receiving an @@account-request@@ deems an @@account-set@@ preferable for the requested change. (Equally valid is to simply accept the request immediately -- perhaps this error is unnecessary?)
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account-set@@ or @@account-request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
[[#changing-keys]]
'''Changing Keys'''
An account message declaring or requesting a key change should be signed by the old key. Subsequent signed messages must be signed by the new key.
[[#verifying-account-data]]
'''Verifying Account Data'''
To request a copy of an account partner's account data for verification, send an @@account-verify-request@@ message containing the account ID:
Example:
[@
{
"account-verify-request": {
"account-id": "550e8400-e29b-41d4-a716-446655440000"
}
}
@]
The immediate reply must contain the complete account data structure of the node receiving the @@account-verify-request@@ as well as a timestamp:
Example:
[@
{
"account-verify": {
"timestamp": "2006-11-07 02:11:28.401000",
"account": {
(...)
}
}
}
@]
Neither message nor reply must be signed.
[[#account-history]]
'''Account History'''
To request from an account partner a list of every signed message that has changed the value of an account field over a certain period, send an @@account-history-request@@:
Example:
[@
{
"account-history-request": {
"starting": "2006-01-01 00:00:00.000000",
"ending": "2006-11-07 02:11:28.401000"
}
}
@]
If the "starting" field is omitted, messages from beginning of the account should be included in the reply. If the "ending" field is omitted, messages up to the present should be included.
The reply is as follows:
[@
{
"account-history": [
(a chronological order of signed messages sent and received over
this account during the requested period that have changed a piece
of shared account data, in the format they were originally sent or
received, including signatures)
]
}
@]
This account history may be used as an audit to find the source of any data discrepancies between partners. This same output may also be taken for each account by a node owner from her own node in order to backup account data or move a node to a different host.
[[#closing-an-account]]
'''Closing an Account'''
To close an account, either party may send an @@account-close@@ message containing the ID of the account to be closed:
Example:
[@
{
"account-close": {
"request-id": 14590,
"account-id": "550e8400-e29b-41d4-a716-446655440000"
}
}
@]
An affirmative reply indicates assent to close the account. An error indicates refusal.
!!! Payments
To allow payments between two nodes that aren't neighbours, Ripple propagates value account-by-account along one or more paths of accounts in the network connecting payer and recipient.
The basic payment process consists of:
# Initializing payment between the payer and recipient nodes
# Preparing the paths to commit the transaction
# Committing the transaction
[[#requesting-payment]]
'''Requesting Payment'''
A node wishing to receive a payment from another node may initiate contact with the potential payer node by sending a @@payment-request@@ message to that node containing:
* unique ID for the payment
* amount
* units
* payment recipient's node's network address
* an explanatory note
[@
{
"payment-request": {
"payment-id": (string),
"amount": (decimal),
"unit": (URI),
"recipient-node-id": (Ripple ID),
"note": (string)
}
}
@]
The @@payment-request@@ may be followed by an @@payment-init@@ message from the potential payer, or ignored.
The @@payment-request@@ message may be authorized by signing it with a certain key, contained in the node owner's smart card, for example, for point-of-sale scenarios where the buyer is unable to communicate directly with his or her node. (Ideally, the smart card would display the payment amount and units to the buyer for approval, otherwise he or she must trust that the seller's terminal displays the same amount as it is asking the smart card to authorize in the @@payment-request@@ message.)
[[#initializing-payment]]
'''Initializing Payment'''
The payer node contacts recipient node and communicates the following in a @@payment-init@@ message:
* unique ID for the payment
* amount to be paid to recipient
* units of payment
* some explanatory text to the recipient
[@
{
"payment-init": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string)
}
}
@]
When generating @@payment-id@@s, nodes should make every effort to ensure they are globally unique in the Ripple network, although this is not strictly necessary for the system to function. Since the @@payment-id@@ field may be an arbitrary string, this shouldn't be too difficult by following a convention such as appending the precise date & time (UTC) to each ID.
The recipient may accept the @@payment-init@@ with an affirmative reply containing a @@payment-accept@@ message with the following data:
* payment ID
* amount to be paid to recipient
* units of payment
* payer's explanatory text echoed back
* recipient's authentication key for payment (used to sign receipts)
* public-key certificate establishing recipient's identity to the payer
[@
{
"payment-accept": {
"payment-id": (string),
"amount": (decimal),
"units": (URI),
"note": (string),
"recipient-receipt-key": (public key data structure),
"recipient-certificate": (certificate data structure)
}
}
@]
This must be signed by the recipient's identifying certificate key, whose certificate identifies the recipient in a way acceptable to the payer, such as being issued (i.e., signed) by an authority recognized by the payer. This message serves as evidence that the recipient participated in the transaction. Thus the signature of the recipient's receipt key on the payment receipts can be irrevocably connected the recipient, proving that the payment was indeed received. The explanatory text can contain text linking the payment to a real-world exchange of goods or services, such as "Payment for auction item #12345".
The recipient may reject the @@payment-init@@ with an error code.
[[#making-promises]]
'''Making Promises (Commit-Request)'''
To prepare the payment paths, the payer sends a @@promise@@ message to the first node on each path, representing its commitment to redeem a valid receipt that can be authenticated with the promise's authentication key up to the amount of credit indicated on the receipt, if presented before the stated deadline.
* payment ID
* path ID
* amount to be held for payment, in path units
* ID of account to be made part of path by this promise being passed
* amount to be held for payment, in account units
* a routing onion (optional)
* a time limit to reach the recipient, in connection time
* promise penalty deadline, in connection time
* daily penalty rate if receipt or path-cancel not received before the penalty deadline
* promise final deadline, in connection time, after which promise expires
* the payer's receipt authentication key for this payment path
* the recipient's receipt authentication key for this payment path
* a timestamp to indicate the time the promise came into effect, in connection time
[@
{
"promise": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal),
"account-id": (string),
"amount": (decimal),
"onion": (routing onion data structure),
"ttl": (date/time string),
"penalty-deadline": (date/time string),
"penalty-rate": (decimal),
"deadline": (date/time string),
"payer-receipt-key": (public key data structure),
"recipient-receipt-key": (public key data structure),
"timestamp": (date/time string)
}
}
@]
Since a promise must be fulfilled if a valid @@receipt@@ is presented, it must effectively hold the required amount on the designated account in such a way that no other transaction may invalidate the payment.
Each node that receives a promise message updates its fields and passes it on to the next node in the path, as determined by data gleaned from the routing onion and/or by extension fields that inform a routing system defined in a protocol extension. At each step, the promise message is signed to the next node by the passing node's authentication key. This serves to establish the integrity and non-repudiability of the promise.
The @@path-id@@ is defined as an ordered list of strings to accommodate routing systems that may use such lists to permit paths to fork into multiple directions while still allowing previous intermediaries in the path to recognize these subpaths and prevent loops from forming. Therefore, a path with ID @@[ A, B ]@@ must be recognized as a forked continuation of the path the same @@payment-id@@ and @@path-id@@ @@[ A ]@@. For the purposes of @@promise@@ and @@receipt@@ routing, these are the same path.
The @@path-amount@@ is invented by the payer and given in arbitrary units (''path units'') particular to each path. This figure gives each intermediary a reference against which to know the value of the @@receipt@@ message that commits the transaction, which will contain a @@path-amount@@ less than or equal to the @@promise@@ @@path-amount@@.
The @@ttl@@ (''time-to-live'') field allows the payer to specify a deadline for the @@promise@@ to reach the recipient. If it should fail to reach the recipient by that time, the latest receiver of the @@promise@@ should release the sender from its promise, and so on back to the payer (see [[Releasing Promises -> #releasing-promises]] below). This field allows the payer to reasonably limit the amount of time it wishes to wait to see whether the path is viable.
The @@penalty-deadline@@ is the time after which the promising node may begin charging a penalty to its partner for having to hold credit it could be using for payment. The penalty is charged continuously at the daily rate specified. Intermediaries should always set a shorter deadline and higher penalty rate on promises out than they have received on promises in, to ensure that they are compensated for overdue @@receipts@@. This provides incentive for the recipient to ensure quick completion or cancellation of each promise path, without requiring hard-and-fast deadlines to come into play so soon that minor delays relaying the receipt back along the path spawn major disputes.
[[#finalizing-payment]]
'''Finalizing the Payment'''
As the recipient receives each @@promise@@, it reports it back to the payer with a @@promise-received@@:
* payment ID
* path ID
* recipient's deadline for accepting the receipts for these paths, in connection time
* final amount of promise in payment units as computed by recipient
[@
{
"promise-received": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"deadline": (date/time string),
"amount": (decimal)
}
}
@]
The recipient's receipt deadline to the payer should be well before the penalty deadline on the @@promise@@ the recipient received.
The recipient can cancel the transaction at any time by sending the payer a @@payment-cancel@@ and releasing its neighbours from their promises with a @@promise-release@@ (see [[Releasing Promises -> #releasing-promises]]). The payer can cancel the transaction by sending the recipient a @@payment-cancel@@, informing it that it can release its neighbours from their promises. Released promises should be propagated back down each payment path to free up those funds for other payments.
When the payer receives a satisfactory set of @@promise-received@@ messages totaling the payment amount or greater, it generates one @@receipt@@ message per @@promise-received@@s, authenticates it individually with the corresponding @@payer-receipt-key@@, and sends it to the recipient before the deadline for doing so:
* payment ID
* path ID
* amount for this path, in path units
[@
{
"receipt": {
"payment-id": (string),
"path-id": [(ordered list of strings)],
"path-amount": (decimal)
}
}
@]
The collection of receipts signed by the payer represents the value of the payment, and once they are given to the recipient, the recipient is considered to have been paid. If any of the receipts is invalid (to be rigorously defined), the amount of that receipt is not considered to have been paid until a valid receipt is issued. The recipient must reply with an error code when receiving an invalid receipt.
The recipient redeems receipts with its neighbours that have issued promises to do so. Each receipt may only partially redeem the value of a single promise, and multiple receipts may be redeemed for a single promise. The unredeemed portion of the promise must be released before the penalty deadline or the penalty must be paid.
[[Protocol/Payment Work Page]]