Protocol /
Protocol06
Protocol.Protocol06 History
Hide minor edits - Show changes to output
August 11, 2012, at 09:31 PM
by - Move exchange request and payment status query to routing extensions
Deleted lines 167-169:
(method-specific data)
},
Changed lines 197-201 from:
While
to:
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
Changed lines 204-206 from:
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
to:
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
Changed lines 210-212 from:
"routing": {"method": (routing method),
(method-specific data)
},
(method-specific data)
}
to:
"amount": (promise amount),
Changed lines 217-218 from:
to:
A signed DELETE to the promise URL by the promisee containing a Promise Release releases the promisor from its Promise.
The response is if accepted:
The response is if accepted:
Changed lines 222-223 from:
HTTP/1.x 201 Created
Location: (exchange request URL)
Location: (exchange request URL)
to:
HTTP/1.x 204 No Content
Changed lines 225-234 from:
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient
to:
!!! Promise Release
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
Changed lines 230-240 from:
Content
Signature: h=
{"payment_id": "(uuid)"
"amount": (promise amount),
"commit": {"method": (commit method),
(method-specific data)
}
}
to:
DELETE (promise URL) HTTP/1.x
Content-Type: application/x-ripple-promise-release+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
Content-Type: application/x-ripple-promise-release+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
Changed lines 237-240 from:
The response is if accepted
to:
Response:
Deleted lines 242-259:
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
[@
DELETE (promise URL) HTTP/1.x
Content-Type: application/x-ripple-promise-release+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
@]
Response:
[@
HTTP/1.x 204 No Content
@]
Deleted lines 243-285:
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
[@
GET (exchange request URL/payment URL) HTTP/1.x
Accept: application/x-ripple-status+json; version=0.6
@]
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-status+json; version=0.6
{"payment_id": "(uuid)",
"payment_status": "(payment status)"
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"promise_status": "(promise status)"
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"promise_status": "(promise status)"
},
(etc.)
]
}
@]
Payment Statuses:
* @@waiting_for_promises@@
* @@cancelled_insufficient_credit@@
* @@cancelled_by_promisee@@
* @@promises_ok@@
Promise Statuses:
* @@waiting@@
* @@promise_ok@@
* @@promise_rejected@@
July 29, 2012, at 04:26 PM
by - missing quotes
Changed line 166 from:
"unit": (optional),
to:
"unit": "(optional)",
Changed line 189 from:
"unit": (optional),
to:
"unit": "(optional)",
July 29, 2012, at 04:25 PM
by - add unit to payment-init and payment-accept
Added line 166:
"unit": (optional),
Added lines 177-178:
The amount represents what is to be received by the recipient hub in its own units. The unit, if present, creates an understanding between payer and recipient as to what that amount represents. The recipient should reject the payment if it doesn't understand or agree with the unit specified by the payer.
Added line 189:
"unit": (optional),
July 25, 2012, at 08:52 PM
by - more fully abstract out routing and commit methods
Changed lines 20-21 from:
where (*) gives the type of message contained in the body, and X.Y gives the version of the Ripple protocol being used. Messages are encoded as JSON, which implies UTF-8.
to:
where (*) gives the type of message contained in the body, and X.Y gives the version of the Ripple protocol being used. Messages are encoded as JSON, which implies UTF-8. Care should be taken to decode numerical values as decimals, not as floating point values, which many JSON packages default to.
Changed lines 121-123 from:
"scale": (integer)
to:
"scale": (integer),
"routing_methods": [(routing methods)],
"commit_methods": [(commit methods)]
"routing_methods": [(routing methods)],
"commit_methods": [(commit methods)]
Added lines 131-132:
Routing and commit methods specify which of these the hub supports. See [[#routing-methods | Routing Methods]] and [[#commit-methods | Commit Methods]].
Changed lines 136-137 from:
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Routing methods specify ways for hubs to publish or otherwise make their exchanges available for other hubs to use in transactions. A basic routing method is:
to:
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Routing methods specify ways for hubs to publish or otherwise make their exchanges available for other hubs to use in transactions, as well as how those exchanges are specified in transactions. A basic routing method is:
Changed lines 140-152 from:
to:
Other routing methods might involve querying the network for a route at payment time so that the existence of non-neighbouring hubs and relationships between them can remain secret.
[[#commit-methods]]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more reliable methods are:
* [[Protocol/Registry Commit Method]]
* [[Protocol/Bare Commit Method]]
Other commit methods might involve registering transactions (or simply rollbacks) in the Bitcoin block chain, Twitter, or elsewhere.
[[#commit-methods]]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more reliable methods are:
* [[Protocol/Registry Commit Method]]
* [[Protocol/Bare Commit Method]]
Other commit methods might involve registering transactions (or simply rollbacks) in the Bitcoin block chain, Twitter, or elsewhere.
Changed lines 167-174 from:
"incoming_promises": [
{"exchange_id": "(uuid)",
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"commit_method": "commit method"
"rate": (buy rate)
},
(etc.)
],
"commit_method": "commit
to:
"routing": {"method": (routing method),
(method-specific data)
},
"commit": {"method": (commit method),
(method-specific data)
}
(method-specific data)
},
"commit": {"method": (commit method),
(method-specific data)
}
Changed lines 187-189 from:
"commit_method": "commit method",
to:
"commit": {"method": (commit method),
(method-specific data)
},
(method-specific data)
},
Changed lines 205-218 from:
"incoming_promises": [
{"exchange_id": "(uuid)",
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
"rate": (buy rate)
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method
to:
"routing": {"method": (routing method),
(method-specific data)
},
"commit": {"method": (commit method),
(method-specific data)
}
(method-specific data)
},
"commit": {"method": (commit method),
(method-specific data)
}
Changed lines 239-241 from:
"commit_method": "(commit method)"
to:
"commit": {"method": (commit method),
(method-specific data)
}
(method-specific data)
}
Changed line 290 from:
to:
"promise_status": "(promise status)"
Deleted lines 314-321:
[[#commit-methods]]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more reliable methods are:
* [[Protocol/Registry Commit Method]]
* [[Protocol/Bare Commit Method]]
July 22, 2012, at 06:56 PM
by - bad link to routing method page
Changed line 134 from:
* [[Protocol/Exchange Publishing]]
to:
* [[Protocol/Exchange Publishing Routing Method]]
July 22, 2012, at 06:55 PM
by - split routing off into separate doc, added links to extensions
Changed lines 129-132 from:
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)//@@:
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/
to:
[[#routing-methods]]
!!! Exchanges & Routing Methods
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Routing methods specify ways for hubs to publish or otherwise make their exchanges available for other hubs to use in transactions. A basic routing method is:
* [[Protocol/Exchange Publishing]]
!! Transactions
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
!!! Exchanges & Routing Methods
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Routing methods specify ways for hubs to publish or otherwise make their exchanges available for other hubs to use in transactions. A basic routing method is:
* [[Protocol/Exchange Publishing]]
!! Transactions
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
Changed lines 144-145 from:
to:
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"incoming_promises": [
{"exchange_id": "(uuid)",
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"commit_method": "commit method"
}
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"incoming_promises": [
{"exchange_id": "(uuid)",
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"commit_method": "commit method"
}
Changed lines 162-163 from:
to:
If the recipient accepts this payment, it responds with a similar message. This Payment Accept response, which is signed by the recipient, will be the payer's proof of payment once the transaction is committed.
Changed lines 165-177 from:
HTTP/1.x 200 OK
Content-Type: application/x-ripple-exchanges+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
[
{"exchange_id": "(uuid)",
"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
Content-Type
Signature: h=content-type,from,date,content-length; ...
(etc.)
]
to:
HTTP/1.x 201 Created
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Changed lines 178-190 from:
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
to:
A signed DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
Changed lines 185-188 from:
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
Content-Type: application/x-ripple-
Accept: application/x-ripple-payment-accept
to:
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
Content-Type: application/x-ripple-exchange-request+json; version=0.6
Deleted lines 188-189:
"memo": "(optional)",
Added lines 196-201:
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
Changed lines 206-207 from:
to:
Response if successful:
Changed lines 210-219 from:
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Content-Type: application/x-ripple-payment-accept+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
to:
Location: (exchange request URL)
Changed lines 213-218 from:
!!! Exchange Request
While
to:
The exchange request is merely informational -- the intermediaries do not reserve any credit at this point. If the deadline passes with no Promises received, the Exchange Request can be discarded.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
Changed lines 224-226 from:
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
to:
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
Signature: h=location,content-type,from,date,content-length; ...
Changed lines 230-243 from:
"incoming_promises": [
{"exchange_id": "(uuid)",
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
{
"amount": (promise amount),
"rate": (buy rate)
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method
to:
"amount": (promise amount),
"commit_method": "(commit method)"
"commit_method": "(commit method)"
Changed lines 235-236 from:
to:
A signed DELETE to the promise URL by the promisee containing a Promise Release releases the promisor from its Promise.
The response is if accepted:
The response is if accepted:
Changed lines 240-241 from:
HTTP/1.x 201 Created
Location: (exchange request URL)
Location: (exchange request URL)
to:
HTTP/1.x 204 No Content
Changed lines 243-252 from:
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient
to:
!!! Promise Release
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
Changed lines 248-256 from:
Content
Signature: h=
{"payment_id": "(uuid)"
"amount": (promise amount),
"commit_method": "(commit method)"
}
to:
DELETE (promise URL) HTTP/1.x
Content-Type: application/x-ripple-promise-release+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
Content-Type: application/x-ripple-promise-release+json; version=0.6
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
Changed lines 255-258 from:
The response is if accepted
to:
Response:
Changed lines 261-264 from:
Any promisee may release
to:
Even if a Promise Release is received after the transaction is committed by whatever commit method is specified, the Promise Release takes precedence in releasing the promisor from any obligation in the transaction.
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
Changed lines 268-272 from:
Signature: h=content-type,from,date,content-length; ...
{"payment_id": "(uuid)"}
to:
GET (exchange request URL/payment URL) HTTP/1.x
Accept: application/x-ripple-status+json; version=0.6
Accept: application/x-ripple-status+json; version=0.6
Deleted lines 271-272:
Deleted lines 272-286:
@]
Even if a Promise Release is received after the transaction is committed by whatever commit method is specified, the Promise Release takes precedence in releasing the promisor from any obligation in the transaction.
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
[@
GET (exchange request URL/payment URL) HTTP/1.x
Accept: application/x-ripple-status+json; version=0.6
@]
[@
Added lines 305-313:
[[#commit-methods]]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more reliable methods are:
* [[Protocol/Registry Commit Method]]
* [[Protocol/Bare Commit Method]]
July 22, 2012, at 05:38 PM
by - Change X-Signature header to just Signature.
Changed lines 55-56 from:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including the X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
to:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including the Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
Changed lines 64-65 from:
Sign the concatenated text with a suitable algorithm and base64url-encode the result. The X-Signature header contains a sequence of semicolon-separated key-value pairs:
to:
Sign the concatenated text with a suitable algorithm and base64url-encode the result. The Signature header contains a sequence of semicolon-separated key-value pairs:
Changed line 73 from:
to:
Signature: a=rsa-sha256; h=content-type,from,date,content-length;
Changed lines 117-118 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed lines 143-144 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed lines 194-195 from:
to:
Signature: h=location,content-type,from,date,content-length; ...
Changed lines 253-254 from:
to:
Signature: h=location,content-type,from,date,content-length; ...
Changed line 276 from:
to:
Signature: h=content-type,from,date,content-length; ...
July 22, 2012, at 05:05 PM
by - Remove payment request - potential for spam and phishing, and probably better outside the protocol
Deleted lines 163-189:
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another hub.
[@
POST (payer hub URL)/paymentrequests/ HTTP/1.x
Content-Type: application/x-ripple-payment-request+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)"
}
@]
Response:
[@
HTTP/1.x 201 Created
Location: (request URL)
@]
A DELETE to this request URL by the requester cancels the payment request. The response:
[@
HTTP/1.x 204 No Content
@]
Changed lines 186-190 from:
A DELETE to this request URL by the requester cancels the payment request.
to:
A DELETE to this request URL by the requester cancels the payment request. The response:
[@
HTTP/1.x 204 No Content
@]
[@
HTTP/1.x 204 No Content
@]
June 18, 2012, at 09:25 PM
by - Hub unit
Changed lines 117-118 from:
{"precision":
to:
X-Signature: h=content-type,from,date,content-length; ...
{"unit": "(value unit)",
"precision": (integer),
{"unit": "(value unit)",
"precision": (integer),
Added lines 124-125:
Unit specifies a reference unit of value that is the denomination of IOUs issued by this hub. Once set, this value cannot change -- a new hub must be created instead.
Changed line 24 from:
to:
The URL of the hub that sent the message.
June 16, 2012, at 08:40 AM
by - exchange_id's and buy rate in exchange requests
Changed lines 24-25 from:
A URL that is the source of the message, usually the hub that sent it.
to:
A URL for the hub that sent the message.
Changed lines 142-143 from:
{"src": "(IOU source hub URL)",
to:
{"exchange_id": "(uuid)",
"src": "(IOU source hub URL)",
"src": "(IOU source hub URL)",
Changed line 197 from:
{"promisor": "(promisor hub URL)",
to:
{"exchange_id": "(uuid)",
Added line 199:
"rate": (buy rate)
Changed line 235 from:
{"promisor": "(promisor hub URL)",
to:
{"exchange_id": "(uuid)",
Added line 237:
"rate": (buy rate)
June 15, 2012, at 06:19 PM
by - hub info: precision & scale; promise URL in location header
Changed lines 103-106 from:
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convertit to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/exchanges/@@:
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert
to:
!!! Hub Info
Hubs publish information for helping other hubs interact with it.
Hubs publish information for helping other hubs interact with it.
Changed lines 108-109 from:
GET (hub URL)/exchanges/ HTTP/1.x
Accept: application/x-ripple-exchanges+json; version=0.6
Accept: application/x-ripple-
to:
GET (hub URL)/info/ HTTP/1.x
Accept: application/x-ripple-info+json; version=0.6
Accept: application/x-ripple-info+json; version=0.6
Changed lines 116-126 from:
Content-Type: application/x-ripple-exchanges+json; version=0.6
X-Signature: h=content-type,from,date,content-length; ...
[
{"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
[
{
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
(etc.)
]
to:
Content-Type: application/x-ripple-info+json; version=0.6
{"precision": (integer),
"scale": (integer)
}
{"precision": (integer),
"scale": (integer)
}
Changed lines 123-135 from:
A commit method is a protocol extension that specifies how a Ripple transaction
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another
to:
Precision and scale give the range of numerical values the hub can process. Precision is the maximum number of digits in a numerical value, and scale is the position of the decimal place, counting from the rightmost digit, around which the digits of precision are allocated.
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/exchanges/@@:
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/exchanges/@@:
Changed lines 130-136 from:
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)"
}
to:
GET (hub URL)/exchanges/ HTTP/1.x
Accept: application/x-ripple-exchanges+json; version=0.6
Accept: application/x-ripple-exchanges+json; version=0.6
Changed lines 134-135 from:
to:
The response is:
Changed lines 137-138 from:
HTTP/1.x 201 Created
Location: (request URL)
Location
to:
HTTP/1.x 200 OK
Content-Type: application/x-ripple-exchanges+json; version=0.6
X-Signature: h=content-type,from,date,content-length; ...
[
{"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
Content-Type: application/x-ripple-exchanges+json; version=0.6
X-Signature: h=content-type,from,date,content-length; ...
[
{"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
Changed lines 151-156 from:
!!! Payment Initiation
The payer hub sends this to
to:
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more secure methods are specified elsewhere.
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another hub.
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more secure methods are specified elsewhere.
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another hub.
Changed lines 165-168 from:
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
Content-Type: application/x-ripple-payment-
Accept: application/x-ripple-payment-accept
to:
POST (payer hub URL)/paymentrequests/ HTTP/1.x
Content-Type: application/x-ripple-payment-request+json; version=0.6
Content-Type: application/x-ripple-payment-request+json; version=0.6
Changed lines 170-177 from:
"memo": "(optional)",
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method
to:
"memo": "(optional)"
Changed lines 174-175 from:
to:
Response:
Changed lines 178-187 from:
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Content-Type: application/x-ripple-payment-accept+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
to:
Location: (request URL)
Changed lines 181-186 from:
A signed DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
to:
A DELETE to this request URL by the requester cancels the payment request.
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
Changed lines 188-190 from:
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
Content-Type: application/x-ripple-
to:
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
Added lines 193-194:
"amount": (amount to be received),
"memo": "(optional)",
"memo": "(optional)",
Deleted lines 200-205:
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
Changed lines 205-206 from:
to:
If the recipient accepts this payment, it responds with a similar message. This Payment Accept response, which is signed by the recipient, will be the payer's proof of payment once the transaction is committed.
Changed lines 209-218 from:
Location: (exchange request URL)
to:
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Content-Type: application/x-ripple-payment-accept+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method",
"payer": "(payer URL)"
}
Changed lines 221-230 from:
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
to:
A signed DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
Changed lines 228-231 from:
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Content-Type: application/x-ripple-promise+json; version=0.6
X-Signature: h=content-type,from,date,content-length; ...
Content-Type: application/x-ripple-
to:
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
Content-Type: application/x-ripple-exchange-request+json; version=0.6
Changed lines 232-234 from:
"amount": (promise amount),
"commit_method": "(commit method)"
to:
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
Response if successful:
[@
HTTP/1.x 201 Created
Location: (exchange request URL)
@]
The exchange request is merely informational -- the intermediaries do not reserve any credit at this point. If the deadline passes with no Promises received, the Exchange Request can be discarded.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
[@
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
Response if successful:
[@
HTTP/1.x 201 Created
Location: (exchange request URL)
@]
The exchange request is merely informational -- the intermediaries do not reserve any credit at this point. If the deadline passes with no Promises received, the Exchange Request can be discarded.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
[@
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Location: (promise URL)
Content-Type: application/x-ripple-promise+json; version=0.6
X-Signature: h=location,content-type,from,date,content-length; ...
{"payment_id": "(uuid)",
Changed line 144 from:
Content-Type: application/x-ripple-payment-init+json; version=0.6
to:
Content-Type: application/x-ripple-payment-request+json; version=0.6
June 13, 2012, at 08:15 AM
by - UUIDs
Added lines 87-94:
!!! UUIDs
UUIDs are encoded as strings with lowercase hexidecimal digits, in the form:
[@
6876cb7f-313c-4986-8c22-5f85988717bf
@]
Added lines 39-45:
Available hash algorithms:
* @@sha1@@
* @@sha256@@
* @@sha512@@
* @@rmd160@@
Changed line 66 from:
X-Signature: a=rsa256; h=content-type,from,date,content-length;
to:
X-Signature: a=rsa-sha256; h=content-type,from,date,content-length;
Changed line 79 from:
* @@rsa256@@: RSASSA-PSS with SHA256.
to:
* @@rsa-sha256@@: RSASSA-PSS with SHA256.
Changed lines 300-304 from:
* waiting_for_promises
to:
* @@waiting_for_promises@@
* @@cancelled_insufficient_credit@@
* @@cancelled_by_promisee@@
* @@promises_ok@@
* @@cancelled_insufficient_credit@@
* @@cancelled_by_promisee@@
* @@promises_ok@@
Changed lines 307-309 from:
* waiting
rejected
to:
* @@waiting@@
* @@promise_ok@@
* @@promise_rejected@@
* @@promise_ok@@
* @@promise_rejected@@
Changed lines 66-72 from:
X-Signature: a=rsa256; h=content-type,from,date,content-length; s=ux_1j86NxE9J5DZ94-sSSlAe8yibrQ4__Xv-ZccW7WWlFMhHU6ZN7_Jne2LGBTeoX66J8CmkNKvnbsfLRAoLJv3HOGEZaQvQJoY_A6ZTKm_AbpN3XRObZdRTS-J_FL4Lv89MUXjKOW8Vbkb4Tw_LeUCeadpPDhuwkCdgSEURjuweWr927cxBqFBU6rlAiFSav7hYgHRBUkPfUuMg85fuBZMzUsUlMLSbKdsjgDSVAB9jfolF-bp2frCtDTc-R08RpoXlznBtajvdkAtlJ_T57PgTDtlDktvheCIbUXZJmkMhSHWsvLsVywrkTVmJo7gD-00aWkLbHfYs7DSu-JW1ow==
to:
X-Signature: a=rsa256; h=content-type,from,date,content-length;
s=ux_1j86NxE9J5DZ94-sSSlAe8yibrQ4__Xv-ZccW7WWlFMhHU6ZN7_Jne2LGBT
eoX66J8CmkNKvnbsfLRAoLJv3HOGEZaQvQJoY_A6ZTKm_AbpN3XRObZdRTS-J_FL
4Lv89MUXjKOW8Vbkb4Tw_LeUCeadpPDhuwkCdgSEURjuweWr927cxBqFBU6rlAiF
Sav7hYgHRBUkPfUuMg85fuBZMzUsUlMLSbKdsjgDSVAB9jfolF-bp2frCtDTc-R0
8RpoXlznBtajvdkAtlJ_T57PgTDtlDktvheCIbUXZJmkMhSHWsvLsVywrkTVmJo7
gD-00aWkLbHfYs7DSu-JW1ow==
s=ux_1j86NxE9J5DZ94-sSSlAe8yibrQ4__Xv-ZccW7WWlFMhHU6ZN7_Jne2LGBT
eoX66J8CmkNKvnbsfLRAoLJv3HOGEZaQvQJoY_A6ZTKm_AbpN3XRObZdRTS-J_FL
4Lv89MUXjKOW8Vbkb4Tw_LeUCeadpPDhuwkCdgSEURjuweWr927cxBqFBU6rlAiF
Sav7hYgHRBUkPfUuMg85fuBZMzUsUlMLSbKdsjgDSVAB9jfolF-bp2frCtDTc-R0
8RpoXlznBtajvdkAtlJ_T57PgTDtlDktvheCIbUXZJmkMhSHWsvLsVywrkTVmJo7
gD-00aWkLbHfYs7DSu-JW1ow==
Added lines 74-75:
(Line breaks are for formatting purposes only -- HTTP headers cannot contain line breaks.)
June 11, 2012, at 04:02 AM
by - single signature header
Changed lines 48-57 from:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including X-Signed-Headers and X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, makea list of headers that should be signed and put that list into the X-Signed-Headers header. For example:
[@
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
@]
To perform the signature, concatenate the following CRLF-separated lines of text:
To sign a request or response, make
[@
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
@]
To perform the signature, concatenate the following CRLF-separated lines of text:
to:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including the X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make an ordered list of headers that should be signed. To perform the signature, concatenate the following CRLF-separated lines of text:
To sign a request or response, make an ordered list of headers that should be signed. To perform the signature, concatenate the following CRLF-separated lines of text:
Changed line 53 from:
* the headers to be signed, in the order and case given in X-Signed-Headers, with no whitespace around the colon for each header, each on a separate line
to:
* the headers to be signed, with the header names in lowercase, in the order determined above, with no whitespace around the colon for each header, each on a separate line
Changed lines 57-59 from:
Sign the result with a suitable algorithm and place the signature in the X-Signature header. Note the name of the signature algorithm in the X-Signature-Algorithm header so the signature can be verified by someone who knows the public key of the signer.
to:
Sign the concatenated text with a suitable algorithm and base64url-encode the result. The X-Signature header contains a sequence of semicolon-separated key-value pairs:
* a=(signature algorithm)
* h=(header list)
* s=(signature)
Example:
[@
X-Signature: a=rsa256; h=content-type,from,date,content-length; s=ux_1j86NxE9J5DZ94-sSSlAe8yibrQ4__Xv-ZccW7WWlFMhHU6ZN7_Jne2LGBTeoX66J8CmkNKvnbsfLRAoLJv3HOGEZaQvQJoY_A6ZTKm_AbpN3XRObZdRTS-J_FL4Lv89MUXjKOW8Vbkb4Tw_LeUCeadpPDhuwkCdgSEURjuweWr927cxBqFBU6rlAiFSav7hYgHRBUkPfUuMg85fuBZMzUsUlMLSbKdsjgDSVAB9jfolF-bp2frCtDTc-R08RpoXlznBtajvdkAtlJ_T57PgTDtlDktvheCIbUXZJmkMhSHWsvLsVywrkTVmJo7gD-00aWkLbHfYs7DSu-JW1ow==
@]
Available signature algorithms:
* @@rsa256@@: RSASSA-PSS with SHA256.
* a=(signature algorithm)
* h=(header list)
* s=(signature)
Example:
[@
X-Signature: a=rsa256; h=content-type,from,date,content-length; s=ux_1j86NxE9J5DZ94-sSSlAe8yibrQ4__Xv-ZccW7WWlFMhHU6ZN7_Jne2LGBTeoX66J8CmkNKvnbsfLRAoLJv3HOGEZaQvQJoY_A6ZTKm_AbpN3XRObZdRTS-J_FL4Lv89MUXjKOW8Vbkb4Tw_LeUCeadpPDhuwkCdgSEURjuweWr927cxBqFBU6rlAiFSav7hYgHRBUkPfUuMg85fuBZMzUsUlMLSbKdsjgDSVAB9jfolF-bp2frCtDTc-R08RpoXlznBtajvdkAtlJ_T57PgTDtlDktvheCIbUXZJmkMhSHWsvLsVywrkTVmJo7gD-00aWkLbHfYs7DSu-JW1ow==
@]
Available signature algorithms:
* @@rsa256@@: RSASSA-PSS with SHA256.
Changed lines 94-96 from:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
X-Signature: ...
X-Signature:
to:
X-Signature: h=content-type,from,date,content-length; ...
Changed lines 166-168 from:
X-Signed-Headers: Location, Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
X-Signature: ...
X-Signature:
to:
X-Signature: h=location,content-type,from,date,content-length; ...
Changed lines 223-225 from:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
X-Signature: ...
X-Signature:
to:
X-Signature: h=content-type,from,date,content-length; ...
Changed lines 247-248 from:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
X-Signature: ...
X-Signature:
to:
X-Signature: h=content-type,from,date,content-length; ...
Changed lines 10-11 from:
Ripple is built on HTTP.
to:
Ripple is built on HTTP. Not all common HTTP headers are included in the Ripple message descriptions here when they don't add any information, but that does not mean they should be omitted by an implementation.
Changed line 38 from:
@@sha1:s+6Gz4gF8G7DPEyV2vaqSL8H9i4=@@
to:
@@sha1:s-6Gz4gF8G7DPEyV2vaqSL8H9i4=@@
Changed lines 48-51 from:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including an X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header, for example:
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header
to:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including X-Signed-Headers and X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header. For example:
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header. For example:
Added line 86:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
Added line 159:
X-Signed-Headers: Location, Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
Added line 217:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
Changed lines 227-228 from:
A signed DELETE to the promise URL by the promisee releases the promisor from its Promise.
to:
A signed DELETE to the promise URL by the promisee containing a Promise Release releases the promisor from its Promise.
Added lines 241-242:
Content-Type: application/x-ripple-promise-release+json; version=0.6
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
Added lines 244-245:
{"payment_id": "(uuid)"}
Changed lines 158-159 from:
to:
X-Signature: ...
Changed lines 168-169 from:
A DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
to:
A signed DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
Changed lines 215-216 from:
to:
X-Signature: ...
Changed lines 224-225 from:
A DELETE to the promise URL by the promisee releases the promisor from its Promise.
to:
A signed DELETE to the promise URL by the promisee releases the promisor from its Promise.
Changed lines 237-238 from:
to:
DELETE (promise URL) HTTP/1.x
X-Signature: ...
X-Signature: ...
Changed lines 46-51 from:
!!! Digital Signatures
In addition to being encrypted, requests and responses containing a body must be signed for non-repudiation, so the receiver can prove to a third party what was sent. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signature-Headers
In
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signature-Headers
to:
!!! Signing for Non-Repudiation
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including an X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header, for example:
In addition to being encrypted, certain requests and responses must be signed for non-repudiation, so the receiver can prove to a third party what was sent. These are indicated by including an X-Signature header in the description. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signed-Headers header, for example:
Changed line 53 from:
X-Signature-Headers: Content-Type, From, Date, Content-Length, X-Signature-Headers, X-Signature-Algorithm
to:
X-Signed-Headers: Content-Type, From, Date, Content-Length, X-Signed-Headers, X-Signature-Algorithm
Changed line 59 from:
* the headers to be signed, in the order and case given in X-Signature-headers, with no whitespace around the colon for each header, each on a separate line
to:
* the headers to be signed, in the order and case given in X-Signed-Headers, with no whitespace around the colon for each header, each on a separate line
Added line 86:
X-Signature: ...
Added lines 30-39:
!!! Encoding Binary Data
Binary data is encoded to UTF-8 using base64url encoding.
!!! Hashing
Whenever a hash is needed here or in protocol extensions, it is suggested to prefix the value with the hashing algorithm used and a colon, to allow new algorithms to be adopted as vulnerabilities are discovered in older algorithms. For example:
@@sha1:s+6Gz4gF8G7DPEyV2vaqSL8H9i4=@@
Binary data is encoded to UTF-8 using base64url encoding.
!!! Hashing
Whenever a hash is needed here or in protocol extensions, it is suggested to prefix the value with the hashing algorithm used and a colon, to allow new algorithms to be adopted as vulnerabilities are discovered in older algorithms. For example:
@@sha1:s+6Gz4gF8G7DPEyV2vaqSL8H9i4=@@
Changed line 53 from:
X-Signature-Headers: Content-Type, From, Date, X-Signature-Headers
to:
X-Signature-Headers: Content-Type, From, Date, Content-Length, X-Signature-Headers, X-Signature-Algorithm
Changed lines 56-59 from:
To perform the signature, concatenate
to:
To perform the signature, concatenate the following CRLF-separated lines of text:
Changed lines 59-65 from:
* the headers to be signed, in the order and case given in X-Signature-headers, with no whitespace around the colon for each header
* empty line
* body
Perform an RSASSA-PSS signature on the resulting UTF-8 bytes, base64-encode the result, and put it in the X-Signature header.
* body
Perform an RSASSA-PSS signature on
to:
* the headers to be signed, in the order and case given in X-Signature-headers, with no whitespace around the colon for each header, each on a separate line
* an empty line
* the request/response body
Sign the result with a suitable algorithm and place the signature in the X-Signature header. Note the name of the signature algorithm in the X-Signature-Algorithm header so the signature can be verified by someone who knows the public key of the signer.
* an empty line
* the request/response body
Sign the result with a suitable algorithm and place the signature in the X-Signature header. Note the name of the signature algorithm in the X-Signature-Algorithm header so the signature can be verified by someone who knows the public key of the signer.
Changed lines 161-162 from:
"commit_method": "commit method"
to:
"commit_method": "commit method",
"payer": "(payer URL)"
"payer": "(payer URL)"
Changed line 197 from:
Promises bind the promisor to transferring value to the promisee if a valid commit token is produced.
to:
Promises bind the promisor to transferring value to the promisee under certain conditions determined by the commit method. For the null commit method, the Promise is the value.
Added lines 1-278:
! Ripple Distributed Transaction Protocol v0.6
!! Purpose
Real-time value transfer through a mutual-credit trust network of hubs that issue IOUs and accept other hubs' IOUs in exchange for their own.
!! HTTP
Ripple is built on HTTP.
!!! Content-Type
Ripple requests and responses have semantically-important content types, of the form
[@
application/x-ripple-*+json; version=X.Y
@]
where (*) gives the type of message contained in the body, and X.Y gives the version of the Ripple protocol being used. Messages are encoded as JSON, which implies UTF-8.
!!! From
A URL that is the source of the message, usually the hub that sent it.
!!! Date
Time and date the message was generated, in GMT (UTC), as specified by HTTP.
!!! Encryption and Authentication
HTTPS with both client and server certificates. Client cert should match domain of From header, server cert should match server domain, as usual.
Decentralized certificate validation of some sort would be preferable to a centralized certificate authority infrastructure, but both can work.
!!! Digital Signatures
In addition to being encrypted, requests and responses containing a body must be signed for non-repudiation, so the receiver can prove to a third party what was sent. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signature-Headers header, for example:
[@
X-Signature-Headers: Content-Type, From, Date, X-Signature-Headers
@]
Note that X-Signature-Headers should always be signed.
To perform the signature, concatenate:
* the HTTP status line
* the headers to be signed, in the order and case given in X-Signature-headers, with no whitespace around the colon for each header
* empty line
* body
Perform an RSASSA-PSS signature on the resulting UTF-8 bytes, base64-encode the result, and put it in the X-Signature header.
!! Network & Routing
!!! Exchange Hubs
Exchange hubs (or just "hubs") are the nodes in the Ripple trust network. A hub accepts IOUs (aka obligations/currency) from other hubs, issues its own IOUs, and is identified by a URL.
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/exchanges/@@:
[@
GET (hub URL)/exchanges/ HTTP/1.x
Accept: application/x-ripple-exchanges+json; version=0.6
@]
The response is:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-exchanges+json; version=0.6
[
{"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
@]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more secure methods are specified elsewhere.
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another hub.
[@
POST (payer hub URL)/paymentrequests/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)"
}
@]
Response:
[@
HTTP/1.x 201 Created
Location: (request URL)
@]
A DELETE to this request URL by the requester cancels the payment request.
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
[@
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
If the recipient accepts this payment, it responds with a similar message. This Payment Accept response, which is signed by the recipient, will be the payer's proof of payment once the transaction is committed.
[@
HTTP/1.x 201 Created
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method"
}
@]
A DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
[@
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
{"payment_id": "(uuid)",
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
Response if successful:
[@
HTTP/1.x 201 Created
Location: (exchange request URL)
@]
The exchange request is merely informational -- the intermediaries do not reserve any credit at this point. If the deadline passes with no Promises received, the Exchange Request can be discarded.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee if a valid commit token is produced.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
[@
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Content-Type: application/x-ripple-promise+json; version=0.6
{"payment_id": "(uuid)",
"promise_url": "(promise URL)",
"amount": (promise amount),
"commit_method": "(commit method)"
}
@]
A DELETE to the promise URL by the promisee releases the promisor from its Promise.
The response is if accepted:
[@
HTTP/1.x 204 No Content
@]
!!! Promise Release
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
[@
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-promise-release+json; version=0.6
@]
Response:
[@
HTTP/1.x 204 No Content
@]
Even if a Promise Release is received after the transaction is committed by whatever commit method is specified, the Promise Release takes precedence in releasing the promisor from any obligation in the transaction.
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
[@
GET (exchange request URL/payment URL) HTTP/1.x
Accept: application/x-ripple-status+json; version=0.6
@]
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-status+json; version=0.6
{"payment_id": "(uuid)",
"payment_status": "(payment status)"
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"promise_status": "(promise status)"
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"promise_status": "(promise status)"
},
(etc.)
]
}
@]
Payment Statuses:
* waiting_for_promises
* cancelled_insufficient_credit
* cancelled_by_promisee
* promises_ok
Promise Statuses:
* waiting
* promise_ok
* promise_rejected
!! Purpose
Real-time value transfer through a mutual-credit trust network of hubs that issue IOUs and accept other hubs' IOUs in exchange for their own.
!! HTTP
Ripple is built on HTTP.
!!! Content-Type
Ripple requests and responses have semantically-important content types, of the form
[@
application/x-ripple-*+json; version=X.Y
@]
where (*) gives the type of message contained in the body, and X.Y gives the version of the Ripple protocol being used. Messages are encoded as JSON, which implies UTF-8.
!!! From
A URL that is the source of the message, usually the hub that sent it.
!!! Date
Time and date the message was generated, in GMT (UTC), as specified by HTTP.
!!! Encryption and Authentication
HTTPS with both client and server certificates. Client cert should match domain of From header, server cert should match server domain, as usual.
Decentralized certificate validation of some sort would be preferable to a centralized certificate authority infrastructure, but both can work.
!!! Digital Signatures
In addition to being encrypted, requests and responses containing a body must be signed for non-repudiation, so the receiver can prove to a third party what was sent. Signatures are performed using the same certificate as used in HTTPS.
To sign a request or response, make a list of headers that should be signed and put that list into the X-Signature-Headers header, for example:
[@
X-Signature-Headers: Content-Type, From, Date, X-Signature-Headers
@]
Note that X-Signature-Headers should always be signed.
To perform the signature, concatenate:
* the HTTP status line
* the headers to be signed, in the order and case given in X-Signature-headers, with no whitespace around the colon for each header
* empty line
* body
Perform an RSASSA-PSS signature on the resulting UTF-8 bytes, base64-encode the result, and put it in the X-Signature header.
!! Network & Routing
!!! Exchange Hubs
Exchange hubs (or just "hubs") are the nodes in the Ripple trust network. A hub accepts IOUs (aka obligations/currency) from other hubs, issues its own IOUs, and is identified by a URL.
!!! Exchanges
Exchanges are how hubs transfer value to each other. A hub can take an IOU from another hub and convert it to a value in its own IOUs at whatever exchange rate it chooses. Hubs publish the exchanges they are willing to make at @@(hub URL)/exchanges/@@:
[@
GET (hub URL)/exchanges/ HTTP/1.x
Accept: application/x-ripple-exchanges+json; version=0.6
@]
The response is:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-exchanges+json; version=0.6
[
{"src": "(IOU source hub URL)",
"rate": (buy rate),
"limit": (max buy amount),
"commit_methods": [(commit methods)]
},
(etc.)
]
@]
!!! Commit Methods
A commit method is a protocol extension that specifies how a Ripple transaction is committed. As described in this document, transactions involve the voluntary, good-faith passing forward of value without any guarantee that it arrives at its destination. This non-commit method is called @@null@@. Other more secure methods are specified elsewhere.
Each exchange offer specifies one or more commit methods for which the specified exchange rate applies.
!! Transactions
!!! Payment Request
A hub can POST this when it wishes to receive a payment from another hub.
[@
POST (payer hub URL)/paymentrequests/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)"
}
@]
Response:
[@
HTTP/1.x 201 Created
Location: (request URL)
@]
A DELETE to this request URL by the requester cancels the payment request.
!!! Payment Initiation
The payer hub sends this to the recipient hub to begin the transaction.
[@
POST (recipient hub URL)/payments/ HTTP/1.x
Content-Type: application/x-ripple-payment-init+json; version=0.6
Accept: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
If the recipient accepts this payment, it responds with a similar message. This Payment Accept response, which is signed by the recipient, will be the payer's proof of payment once the transaction is committed.
[@
HTTP/1.x 201 Created
Location: (payment URL)
Content-Type: application/x-ripple-payment-accept+json; version=0.6
{"payment_id": "(uuid)",
"amount": (amount to be received),
"memo": "(optional)",
"commit_method": "commit method"
}
@]
A DELETE to the payment URL by the payer cancels the payment. The payment URL can also receive payment status requests from the payer.
!!! Exchange Request
While the payer is initiating payment with the recipient, it contacts intermediary hubs it wishes to use to route the payment to the recipient by a sequence of exchanges. The payer tells each intermediary where to route Promises with an Exchange Request:
[@
POST (intermediary hub URL)/exchangerequests/ HTTP/1.x
Content-Type: application/x-ripple-exchange-request+json; version=0.6
{"payment_id": "(uuid)",
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"amount": (promise amount),
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"amount": (promise amount),
},
(etc.)
],
"commit_method": "commit method"
}
@]
Response if successful:
[@
HTTP/1.x 201 Created
Location: (exchange request URL)
@]
The exchange request is merely informational -- the intermediaries do not reserve any credit at this point. If the deadline passes with no Promises received, the Exchange Request can be discarded.
The exchange request URL can receive payment status requests from the payer.
!!! Promise
Promises bind the promisor to transferring value to the promisee if a valid commit token is produced.
Once all intermediaries have accepted their instructions, the payer sends a Promise forward to the first intermediary or intermediaries, who then pass their own Promises forward along the payment route as directed by the payer's Exchange Requests, until Promises adding up to the full payment amount are received by the recipient.
[@
POST (intermediary/recipient hub URL)/promises/ HTTP/1.x
Content-Type: application/x-ripple-promise+json; version=0.6
{"payment_id": "(uuid)",
"promise_url": "(promise URL)",
"amount": (promise amount),
"commit_method": "(commit method)"
}
@]
A DELETE to the promise URL by the promisee releases the promisor from its Promise.
The response is if accepted:
[@
HTTP/1.x 204 No Content
@]
!!! Promise Release
Any promisee may release the promisor from its Promise by sending a Promise Release to the promisor.
[@
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-promise-release+json; version=0.6
@]
Response:
[@
HTTP/1.x 204 No Content
@]
Even if a Promise Release is received after the transaction is committed by whatever commit method is specified, the Promise Release takes precedence in releasing the promisor from any obligation in the transaction.
!!! Payment Status Query
In order to help determine why a payment stalled or otherwise failed, and help determine another route, the payer can ask the other participants for the status of the payment at their server.
[@
GET (exchange request URL/payment URL) HTTP/1.x
Accept: application/x-ripple-status+json; version=0.6
@]
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-status+json; version=0.6
{"payment_id": "(uuid)",
"payment_status": "(payment status)"
"incoming_promises": [
{"promisor": "(promisor hub URL)",
"promise_status": "(promise status)"
},
(etc.)
],
"outgoing_promises": [
{"promisee": "(promisee hub URL)",
"promise_status": "(promise status)"
},
(etc.)
]
}
@]
Payment Statuses:
* waiting_for_promises
* cancelled_insufficient_credit
* cancelled_by_promisee
* promises_ok
Promise Statuses:
* waiting
* promise_ok
* promise_rejected