Recent Changes - Search:
Protocol /

RegistryCommitMethod

Ripple Protocol Commit Method: Registry

See Commit Methods.

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.

Commit Method Name

This commit method is called registry.

Network & Routing

Hub Info

The Info message also contains: 

"max-deadline-length": (time in seconds)

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. 

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
Signature: h=content-type,from,date,content-length; ...

[
	{"url": "(registry URL)",
	 "key": "(public key fingerprint)"
	},
	(etc.)
]

Commit Method-Specific Data

Where commit method-specific data is required, use the following: 

 "commit": {
	"registry": {
		"url": "(registry URL)",
		"key": "(key fingerprint)"
	},
	"deadline": "(commit deadline)",
	"commit_token_hash": "(commit token hash)"
 }

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. 

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.

Response: 

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)
Signature: h=content-type,from,date,content-length; ...

{"commit_token": "(commit token)",
 "commit_token_hash": "(commit token hash)",
 "registry_key": "(registry key fingerprint)",
}

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: 

HTTP/1.x 404 Not Found
Content-Type: application/x-ripple-no-commit+json; version=X.Y
From: (registry URL)
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

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.