Protocol /
RegistryCommitMethod
Protocol.RegistryCommitMethod History
Hide minor edits - Show changes to output
July 25, 2012, at 08:54 PM
by - update to match more-commit-abstracted core protocol
Changed lines 49-54 from:
!! Transactions
!!! Payment Initiation
Add the registry to be used for the transaction and the deadline for the commit to be timestamped to the payment-init message:
!!! Payment Initiation
Add the registry to be used for
to:
!! Commit Method-Specific Data
Where commit method-specific data is required, use the following:
Where commit method-specific data is required, use the following:
Changed lines 54-58 from:
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)"
"key"
to:
"commit": {
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
}
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
}
Changed lines 64-65 from:
The recipient adds these fields to the Payment Accept response, as well generating a secret commit token and including its hash. The secret commit token should be randomly generated with at least as many bits as the hash method used.
to:
The commit token hash is generated by the recipient, and is omitted from the payment init message, since it is not yet known.
!! Transactions
The following transaction messages are used to commit a payment.
!!! Commit
The recipient decides to attempt to commit the transaction, by sending the secret commit token to the registry to be timestamped, along with the commit token hash and registry key as extra verification against software errors or other miscommunication.
!! Transactions
The following transaction messages are used to commit a payment.
!!! Commit
The recipient decides to attempt to commit the transaction, by sending the secret commit token to the registry to be timestamped, along with the commit token hash and registry key as extra verification against software errors or other miscommunication.
Changed lines 75-79 from:
"url"
"key"
},
to:
POST (registry URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
Accept: application/x-ripple-registry-commit+json; version=X.Y
{"commit_token": "(commit token)",
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
Accept: application/x-ripple-registry-commit+json; version=X.Y
{"commit_token": "(commit token)",
Added lines 81-82:
"registry_key": "(registry key fingerprint)",
}
}
Changed lines 85-90 from:
The recipient may shorten the deadline here if it wishes.
!!! Exchange Request
Must contain same values as the Payment Accept:
!!! Exchange Request
Must contain same values as the Payment Accept
to:
The registry verifies the hash, and responds with:
Changed lines 88-93 from:
"url": "(
"key"
},
"deadline"
to:
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
Changed lines 101-103 from:
Must contain same values as
to:
This commit message, which is timestamped in the Date header and signed by the registry, invokes a Promise if and only if:
* the commit token hash matches the one on the Promise
* the commit token hash is the correct hash of the commit token
* the timestamp is earlier than or equal to the commit deadline in the Promise
The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token/hash combo once.
Each promisee, once it receives a valid timestamped commit message, should pass that response message, including status line and all signed headers, back to the promisors whose promises it holds.
* the commit token hash matches the one on the Promise
* the commit token hash is the correct hash of the commit token
* the timestamp is earlier than or equal to the commit deadline in the Promise
The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token/hash combo once.
Each promisee, once it receives a valid timestamped commit message, should pass that response message, including status line and all signed headers, back to the promisors whose promises it holds.
Changed lines 114-118 from:
"url"
"key": "(key fingerprint)"
},
"deadline"
to:
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit-response+json; version=X.Y
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
Content-Type: application/x-ripple-registry-commit-response+json; version=X.Y
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
Added lines 126-127:
"registry_key": "(registry key fingerprint)",
}
}
Changed lines 130-190 from:
The recipient decides to attempt to commit the transaction, by sending the secret commit token to the registry to be timestamped, along with the commit token hash and registry key as extra verification against software errors or other miscommunication.
[@
POST (registry URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
Accept: application/x-ripple-registry-commit+json; version=X.Y
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)"
"registry_key": "(registry key fingerprint)",
}
@]
The registry verifies the hash, and responds with:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
This commit message, which is timestamped in the Date header and signed by the registry, invokes a Promise if and only if:
* the commit token hash matches the one on the Promise
* the commit token hash is the correct hash of the commit token
* the timestamp is earlier than or equal to the commit deadline in the Promise
The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token/hash combo once.
Each promisee, once it receives a valid timestamped commit message, should pass that response message, including status line and all signed headers, back to the promisors whose promises it holds.
[@
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit-response+json; version=X.Y
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
Note that the body of the POST is the signed HTTP response from the registry.
to:
Note that the body of the POST is the signed HTTP response from the registry.
Response:
Response:
July 22, 2012, at 06:59 PM
by - link back to relevant section in core protocol doc
Added lines 3-4:
See [[Protocol/Protocol06#commit-methods | Commit Methods]].
Changed line 19 from:
to:
"max-deadline-length": (time in seconds)
July 22, 2012, at 05:39 PM
by - Replace X-Signature header with just Signature to match base protocol.
Changed lines 36-37 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed lines 122-123 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed lines 151-152 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed lines 182-183 from:
to:
Signature: h=content-type,from,date,content-length; ...
Changed line 198 from:
to:
Signature: h=content-type,from,content-length; ...
June 15, 2012, at 06:23 PM
by - deadline in info message
Changed lines 12-13 from:
to:
!!! Hub Info
The Info message also contains:
The Info message also contains:
Changed lines 17-18 from:
Accept: application/x-ripple-registries+json; version=X.Y
to:
"max-deadline-length": (time in seconds)
Changed lines 20-21 from:
The response gives a list of registries by their URL and their public key fingerprint, given by a algorithm-prefixed hash.
to:
The max deadline length is the maximum length of time the hub will hold credit for a Promise. Exchange Requests with a deadline further away will likely be refused.
!!! Registries
Each hub publishes a list of registries that it will accept as commit authorities for transactions in which it participates.
!!! Registries
Each hub publishes a list of registries that it will accept as commit authorities for transactions in which it participates.
Added lines 27-33:
GET (hub URL)/registries/ HTTP/1.x
Accept: application/x-ripple-registries+json; version=X.Y
@]
The response gives a list of registries by their URL and their public key fingerprint, given by a algorithm-prefixed hash.
[@
Accept: application/x-ripple-registries+json; version=X.Y
@]
The response gives a list of registries by their URL and their public key fingerprint, given by a algorithm-prefixed hash.
[@
Changed lines 38-39 from:
"trusted_registries":
to:
[
Changed lines 43-44 from:
}
to:
]
Deleted lines 44-45:
The max deadline length is the maximum length of time the hub will hold credit for a Promise. Exchange Requests with a deadline further away will likely be refused.
Changed lines 3-4 from:
Commit registries are trusted authorities that tell participants whether a transaction was committed or not by timestamping a secret commit token generated by the payment recipient. Under this method, Ripple transactions are fully atomic.
to:
Commit registries are trusted authorities that tell participants whether a transaction was committed or not by timestamping a secret commit token generated by the payment recipient. Under this method, Ripple transactions are fully atomic assuming registries don't cheat.
Changed lines 122-125 from:
This commit message, which is timestamped in the Date header and signed by the registry, irrevocably triggers the commit if, and only if, the timestamp is earlier than or equal to the commit deadline in the Promises. The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token value once.
A registry must only ever timestamp a particular commit token value
to:
This commit message, which is timestamped in the Date header and signed by the registry, invokes a Promise if and only if:
* the commit token hash matches the one on the Promise
* the commit token hash is the correct hash of the commit token
* the timestamp is earlier than or equal to the commit deadline in the Promise
The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token/hash combo once.
* the commit token hash matches the one on the Promise
* the commit token hash is the correct hash of the commit token
* the timestamp is earlier than or equal to the commit deadline in the Promise
The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token/hash combo once.
Changed lines 182-183 from:
to:
An intermediary receiving a valid timestamped commit from the registry should, as before, pass it back to its promisors.
If the registry has not seen that commit token hash as of the deadline, it asserts that it has no knowledge of such a token as of the deadline given:
If the registry has not seen that commit token hash as of the deadline, it asserts that it has no knowledge of such a token as of the deadline given:
Deleted line 196:
Changed lines 201-208 from:
* @@commit_ok@@
to:
* @@commit_ok@@
!! Cheating & Registry Trustworthiness
If a registry cheats by issuing a Commit to some intermediaries, and a No-Commit to others, this will be discovered when the messages are passed back towards the payer. The conflicting messages can then be published as proof of the registry's unreliability, and no one should trust it thereafter.
If a registry fails to provide timely responses, it should also not be used. It ought to be possible to design registries that are very reliable.
!! Cheating & Registry Trustworthiness
If a registry cheats by issuing a Commit to some intermediaries, and a No-Commit to others, this will be discovered when the messages are passed back towards the payer. The conflicting messages can then be published as proof of the registry's unreliability, and no one should trust it thereafter.
If a registry fails to provide timely responses, it should also not be used. It ought to be possible to design registries that are very reliable.
Added lines 1-195:
! Ripple Protocol Commit Method: Registry
Commit registries are trusted authorities that tell participants whether a transaction was committed or not by timestamping a secret commit token generated by the payment recipient. Under this method, Ripple transactions are fully atomic.
!!! Commit Method Name
This commit method is called @@registry@@.
!!! Hashing
!! Network & Routing
Each hub publishes a list of registries that it will accept as commit authorities for transactions in which it participates.
[@
GET (hub URL)/registries/ HTTP/1.x
Accept: application/x-ripple-registries+json; version=X.Y
@]
The response gives a list of registries by their URL and their public key fingerprint, given by a algorithm-prefixed hash.
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registries+json; version=X.Y
X-Signature: h=content-type,from,date,content-length; ...
{"max-deadline-length": (time in seconds),
"trusted_registries": [
{"url": "(registry URL)",
"key": "(public key fingerprint)"
},
(etc.)
]
}
@]
The max deadline length is the maximum length of time the hub will hold credit for a Promise. Exchange Requests with a deadline further away will likely be refused.
!! Transactions
!!! Payment Initiation
Add the registry to be used for the transaction and the deadline for the commit to be timestamped to the payment-init message:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)"
@]
The recipient adds these fields to the Payment Accept response, as well generating a secret commit token and including its hash. The secret commit token should be randomly generated with at least as many bits as the hash method used.
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
@]
The recipient may shorten the deadline here if it wishes.
!!! Exchange Request
Must contain same values as the Payment Accept:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
@]
!!! Promise
Must contain same values as the Payment Accept:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)"
"commit_token_hash": "(commit token hash)",
@]
!!! Commit
The recipient decides to attempt to commit the transaction, by sending the secret commit token to the registry to be timestamped, along with the commit token hash and registry key as extra verification against software errors or other miscommunication.
[@
POST (registry URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
Accept: application/x-ripple-registry-commit+json; version=X.Y
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)"
"registry_key": "(registry key fingerprint)",
}
@]
The registry verifies the hash, and responds with:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
This commit message, which is timestamped in the Date header and signed by the registry, irrevocably triggers the commit if, and only if, the timestamp is earlier than or equal to the commit deadline in the Promises. The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token value once.
Each promisee, once it receives a valid timestamped commit message, should pass that response message, including status line and all signed headers, back to the promisors whose promises it holds.
[@
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit-response+json; version=X.Y
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
Note that the body of the POST is the signed HTTP response from the registry.
[@
HTTP/1.x 204 No Content
@]
!!! Registry Commit Query
Transaction participants may, once the deadline has passed, check with the registry to see if the transaction has been committed.
[@
GET (registry URL)?hash=(commit token hash)&deadline=(deadline) HTTP/1.x
Accept: application/x-ripple-commit+json; version=X.Y, application/x-ripple-no-commit+json; version=X.Y
@]
If the registry has a commit token timestamped on or before the given deadline, it responds with the timestamped commit response it has already produced:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
If not, the registry asserts that it has no knowledge of such a token as of the deadline given:
[@
HTTP/1.x 404 Not Found
Content-Type: application/x-ripple-no-commit+json; version=X.Y
From: (registry URL)
X-Signature: h=content-type,from,content-length; ...
{"commit_token_hash": "(commit token hash)",
"deadline": "(deadline)"
}
@]
!!! Payment Status Query
* @@waiting_for_commit@@
* @@cancelled_by_registry@@
* @@commit_ok@@
Commit registries are trusted authorities that tell participants whether a transaction was committed or not by timestamping a secret commit token generated by the payment recipient. Under this method, Ripple transactions are fully atomic.
!!! Commit Method Name
This commit method is called @@registry@@.
!!! Hashing
!! Network & Routing
Each hub publishes a list of registries that it will accept as commit authorities for transactions in which it participates.
[@
GET (hub URL)/registries/ HTTP/1.x
Accept: application/x-ripple-registries+json; version=X.Y
@]
The response gives a list of registries by their URL and their public key fingerprint, given by a algorithm-prefixed hash.
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registries+json; version=X.Y
X-Signature: h=content-type,from,date,content-length; ...
{"max-deadline-length": (time in seconds),
"trusted_registries": [
{"url": "(registry URL)",
"key": "(public key fingerprint)"
},
(etc.)
]
}
@]
The max deadline length is the maximum length of time the hub will hold credit for a Promise. Exchange Requests with a deadline further away will likely be refused.
!! Transactions
!!! Payment Initiation
Add the registry to be used for the transaction and the deadline for the commit to be timestamped to the payment-init message:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)"
@]
The recipient adds these fields to the Payment Accept response, as well generating a secret commit token and including its hash. The secret commit token should be randomly generated with at least as many bits as the hash method used.
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
@]
The recipient may shorten the deadline here if it wishes.
!!! Exchange Request
Must contain same values as the Payment Accept:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)",
"commit_token_hash": "(commit token hash)"
@]
!!! Promise
Must contain same values as the Payment Accept:
[@
"registry": {
"url": "(registry URL)",
"key": "(key fingerprint)"
},
"deadline": "(commit deadline)"
"commit_token_hash": "(commit token hash)",
@]
!!! Commit
The recipient decides to attempt to commit the transaction, by sending the secret commit token to the registry to be timestamped, along with the commit token hash and registry key as extra verification against software errors or other miscommunication.
[@
POST (registry URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
Accept: application/x-ripple-registry-commit+json; version=X.Y
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)"
"registry_key": "(registry key fingerprint)",
}
@]
The registry verifies the hash, and responds with:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
This commit message, which is timestamped in the Date header and signed by the registry, irrevocably triggers the commit if, and only if, the timestamp is earlier than or equal to the commit deadline in the Promises. The timestamp establishes the time the transaction was committed.
A registry must only ever timestamp a particular commit token value once.
Each promisee, once it receives a valid timestamped commit message, should pass that response message, including status line and all signed headers, back to the promisors whose promises it holds.
[@
POST (promise URL) HTTP/1.x
Content-Type: application/x-ripple-registry-commit-response+json; version=X.Y
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
Note that the body of the POST is the signed HTTP response from the registry.
[@
HTTP/1.x 204 No Content
@]
!!! Registry Commit Query
Transaction participants may, once the deadline has passed, check with the registry to see if the transaction has been committed.
[@
GET (registry URL)?hash=(commit token hash)&deadline=(deadline) HTTP/1.x
Accept: application/x-ripple-commit+json; version=X.Y, application/x-ripple-no-commit+json; version=X.Y
@]
If the registry has a commit token timestamped on or before the given deadline, it responds with the timestamped commit response it has already produced:
[@
HTTP/1.x 200 OK
Content-Type: application/x-ripple-registry-commit+json; version=X.Y
From: (registry URL)
Date: (timestamp)
Content-Length: (content length)
X-Signature: h=content-type,from,date,content-length; ...
{"commit_token": "(commit token)",
"commit_token_hash": "(commit token hash)",
"registry_key": "(registry key fingerprint)",
}
@]
If not, the registry asserts that it has no knowledge of such a token as of the deadline given:
[@
HTTP/1.x 404 Not Found
Content-Type: application/x-ripple-no-commit+json; version=X.Y
From: (registry URL)
X-Signature: h=content-type,from,content-length; ...
{"commit_token_hash": "(commit token hash)",
"deadline": "(deadline)"
}
@]
!!! Payment Status Query
* @@waiting_for_commit@@
* @@cancelled_by_registry@@
* @@commit_ok@@