Public Comb Protocol
Public comb protocol description
Public comb protocol is a request/response GET api built on top of HTTP/HTTPS or similar.
Usual public comb protocol port is 21212 (localhost, http), 80 (http), or 443 (https).
Basic concepts
Active part - an url substring after the last '/' character of the url.
Dot count - how many times a '.' character occurs in the active part.
Name - a prefix of the active part ending in front of the first '.' character.
Reserved name - a name string (protocol constant) that's handled specially.
Second part - a substring of the active part between the first and second '.' character
Third part - a substring of the active part between the second and third '.' character
Fourth part - a substring of the active part between the third and fourth '.' character
Fail response
Fail response consists of a fixed response JSON:
{"Success":false}
A future revision of this protocol will revise this to be a JSONP instead.
Dot count 0 request - redirect
It is not prescribed by the public comb protocol how the request with dot count of 0 is handled. Usual behavior is a Content-Type text/html response with a meta tag indicating a redirect to a specific wallet software url with a status code of 301 indicating a redirect.
Dot count 1 request - get block
Name is parsed, and checked to be one of the following reserved names:
"main", "wasm_exec", "wasm", "combfullui", "index", "style"
If name is a reserved name the public comb protocol does not prescribe a specific behavior, usually a specific wallet software payload is delivered to the client.
If name consists of 16 ascii digits, a getblock call is invoked, otherwise a Fail response is returned.
Getblock call
The name is interpreted as a block height integer, an implementation specific leveldb content is returned to the client for the block height. The response to the getblock call is a JSONP with the following JSON fields:
Testnet - a boolean indicating the testnet for true and mainnet for false.
DbData - a key value dictionary of string keys and string values, leveldb format specific.
Success - must be true.
Example
http://127.0.0.1:21212/0000000000481824.js
Dot count 2 request - base range
Name is parsed, and checked to be one of the following reserved names:
"wasm_exec", "index", "style"
If name is a reserved name the public comb protocol does not prescribe a specific behavior, usually a specific wallet software payload is delivered to the client.
If name consists of 16 ascii digits, and the second part consists of 16 ascii digits, a get base range call is invoked, otherwise a Fail response is returned.
Base range call
The call returns all the combbases between min height (Name) and max height (Second part) interpreted as two integers (inclusive). The response to the Base range call is a JSONP with the following JSON fields:
Testnet - a boolean indicating the testnet for true and mainnet for false.
Combbases - an array of comb base objects. The Combbase, Height of each object is unique. The array does not need to be sorted.
Combbase - 64 characters (hex) string, the combbase commitment.
Height - integer, the block height of the combbase commitment.
Success - must be true.
Example
http://127.0.0.1:21212/0000000000481824.0000000000482884.js
Dot count 3, 4 request - deprecated
These calls are deprecated and were removed. Currently, they do not do anything.
Dot count 5 request - get commits
Lookups commits by commit prefixes in the Haircomb commitment set. Parameters:
Number of hash functions to use per value in the response bloom filter (00000001-00000050)
Tweak for use in the response bloom filter (0000000000000000-0000004294967295)
Prefix is the number of bytes of each prefix in the prefixesValues list (00000003-00000016)
Maximum block height which is queried (0000000000000000-9999999999999999)
Hex encoded prefix values list of concatenated prefix values. Each prefix is the same number of bytes long.
URLs of size up to 2MB must be handled correctly.
Get commits call
The ram database of commits is first iterated. Every commit in ram is checked to match the request set of commit prefixes. If the commit in ram matches any commit prefix, the commit is added to the result set.
If the node is pruned, the disk database is iterated next using the prefix bloom (if prefx > 0) mechanism. Every commitment prefix is restored from the request list and looked up on disk. If there is a match, the commit is added to the result set.
The result set only holds up to 256 commits verbatim, if more than 256 commits match the bloom, then the result is a bloom filter (base 64, not url encoding) and Commits is null.
A count of matched commitments is also returned.
Example
http://127.0.0.1:21212/00000001.0000000000000000.00000009.9999999999999999.cdbf909e935c855d3e.js
Last updated