REST: grid sporks
The endpoints under /gridspork show the network-wide settings the board maintains, see
Grid sporks, and carry a spork in and out of the node. They are part of the
REST interface and need the bearer token like every other endpoint.
There are two kinds. The JSON endpoints show what the node holds and change nothing. The wire endpoints
carry a spork in the form peers exchange, so that a board member can sign on their own machine: the node checks
the signatures and never signs. hedgehog cli is a client of both, see Changing a spork.
The type. TYPE in a path is one of MINT_STORAGE, MINT_SUPPLY, VESTING_STORAGE, STORAGE,
LEDGER_BLACKLIST, LEDGER_FEE, COMMUNICATION, STATISTICS_PUBKEY and BOARD_KEYS. A spork that the node
does not hold is answered with 204, an empty body, on every endpoint that says so below.
Without --preview. A node run without the hidden --preview switch takes no STORAGE, LEDGER_BLACKLIST,
LEDGER_FEE or COMMUNICATION spork, as release 0.0.9 leaves their parts off, see
Grid sporks. Their JSON endpoints answer 503 with
This release does not take the <TYPE> spork, the wire endpoints treat them as types the node does not know,
and GET /gridspork and GET /gridspork/log leave them out. The other endpoints answer as below.
The JSON endpoints
GET /gridspork
An overview of the mint storage, mint supply and vesting storage sporks. The types that count for nothing, as the
key that signed them was switched off since, are listed in notCounting.
GET /gridspork/log
The signature history of every stored spork: who signed each change and when. The signers that are switched off are
listed in switchedOff. 204 when the node holds no spork.
GET /gridspork/board-keys
The board keys. It answers epoch, builtInKeys, chain, active and inactive. Each change in chain holds
sequence, madeAt, previous, active and approvals, and each approval a key and its signature;
previous is the digest the change follows on. active and inactive are the keys that the chain makes active
now and those that were active before, see Changing the board keys.
GET /gridspork/pending
The proposals that wait for a co-signature, each with its digest. 204 when there are none.
GET /gridspork/mint-storage
The mint storage spork, the mints promised to addresses. 204 when unset.
GET /gridspork/mint-storage/{address}/{height}
The amount of one entry. 404 when that key has none, 400 when the address or the height does not fit its kind, 204 when the spork is unset.
GET /gridspork/mint-supply
The mint supply spork. 204 when unset.
GET /gridspork/vesting-storage
The vesting storage spork. 204 when unset.
GET /gridspork/vesting-storage/{address}
The vesting schedule of one address. 404 when it has none, 204 when the spork is unset.
GET /gridspork/storage
The storage spork, which switches on and sets the network storage. 204 when unset, 503
without --preview.
GET /gridspork/ledger-blacklist
The ledger blacklist spork, see Ledger sporks. 204 when unset, 503 without --preview.
GET /gridspork/ledger-fee
The ledger fee spork, see Ledger sporks. 204 when unset, 503 without --preview.
GET /gridspork/communication
The communication spork, which switches on the SOCKS proxy and sets how its chains are built.
204 when unset, and the proxy refuses every request until it is set; 503 without --preview. It cannot be
written over this interface: a
change goes through the wire endpoints below, signed by the board like every other spork.
Every spork the JSON endpoints show holds counting, false for one that a key signed which the board has switched
off since.
The wire endpoints
A spork is signed on the machine of a board member, never on the node. A change over a stored spork is held as a proposal until a second board key has co-signed it, and only then is it stored and sent to the network.
GET /gridspork/wire/{TYPE}
| Answer | Meaning |
|---|---|
| 200 | The stored spork in wire form, application/octet-stream |
| 204 | The node holds none of that type |
| 404 | The type is not one the node knows, or one it does not take without --preview |
GET /gridspork/pending/{digest}
| Answer | Meaning |
|---|---|
| 200 | The proposal in wire form |
| 404 | No proposal has that digest |
POST /gridspork/wire
The body is a signed spork, application/octet-stream, at most 16 MiB (16,777,216 bytes), which is what a peer may
send. A body above 16 MiB is answered with 413.
| Answer | Meaning |
|---|---|
| 200 | The node stored the spork and sent it on to its peers |
| 202 | The node holds it as a proposal until a second board key co-signs it, and sent it on. The body is PendingSporkInfo as JSON: type, timeStamp, expires, signer, digest and data |
| 400 | The body is not a spork, holds data no node can act on, or is of a type the node does not take without --preview (This node takes no <TYPE> spork); the reason is in plain text |
| 401 | No current board key signed the spork, or no second current board key co-signed it: No current board key signed the spork, or no second one co-signed it |
| 409 | The spork does not follow on the stored spork and the proposal held: The spork does not follow on the stored spork and the proposal held, it is stamped more than 2 minutes ahead of the clock of the node: The spork is stamped further ahead of the clock of this node than clocks drift apart, or it is a proposal stamped more than 60 minutes before the clock of the node, such as one stamped at the epoch: The proposal is stamped more than 60 minutes from the clock of this node |
The data is judged before any signature is, so content that no node can act on is never held or sent.
A proposal that renews the stored spork does not take the place of a proposal of a change of that type that waits
for its co-signature, and is answered with 409 and
The spork does not follow on the stored spork and the proposal held. A proposal of a change takes the place of a
waiting renewal, even one stamped up to 60 minutes after it.
A copy of the stored version, with its time stamp and everything its signatures cover, that two different active board keys signed takes the place of a stored copy that counts for nothing, as a key that signed it was switched off since. The node answers 200 and sends it on. A stored copy that counts keeps its place, and a board keys spork takes no such copy.
A board keys spork is judged by its chain rather than by the data of the other types. Its signatures are checked against the keys its own chain ends in, and the node stores it only when it carries the whole stored chain and is longer, or the same chain and newer. A chain that neither holds the other is a fork, against which the node keeps its own, see Changing the board keys.
In the source
application/src/main/java/org/unigrid/hedgehog/server/rest/GridSporkWireResource.java: the wire endpoints that hand out a stored spork or a proposal and take a signed spork back.application/src/main/java/org/unigrid/hedgehog/server/rest/GridSporkResource.java: sporks, proposals, signature histories and the chain of board keys as JSON. The other spork resources sit in the same package:MintStorageResource,VestingStorageResourceandSporkResource, which shows the mint supply, storage, ledger blacklist, ledger fee and communication sporks and answers 503 for those a node does not take.application/src/main/java/org/unigrid/hedgehog/model/spork/SporkRelease.java: the types a node takes.application/src/main/java/org/unigrid/hedgehog/model/spork/BoardKeysInfo.java: the board keys chain, as/gridspork/board-keysanswers it.application/src/main/java/org/unigrid/hedgehog/model/network/codec/SporkWire.java: the wire form.application/src/main/java/org/unigrid/hedgehog/client/rest/SporkClient.java: the client of the wire endpoints that the command line uses.