Renewing sporks

Part of Board instructions. How to sign sporks again after the board switches off a key.

flowchart TD
    O["The board switches off key X"] --> N["Sporks that X signed stay stored,<br/>but count for nothing and are not passed on"]
    N --> Q{"Where is the data?"}
    Q -->|"on the nodes"| R["Member A: gridspork-renew --switched-off TYPE"]
    R --> C["Member B, on a node that stores the spork:<br/>gridspork-cosign --switched-off TYPE digest"]
    Q -->|"only in a spork database file"| F["util spork-db sign, by two members,<br/>then util spork-db import"]
    C --> D["Signed by two active keys:<br/>it counts again and spreads"]
    F --> D

A spork that a switched-off key signed stays in spork.db but counts for nothing: readers act only on a spork that two active board keys signed, and a node does not publish it. gridspork-set and gridspork-grow refuse to build on it: The MINT_SUPPLY spork that the node holds is signed by <16 hex> (switched off) and <16 hex> and counts for nothing; renew it first with gridspork-renew --switched-off MINT_SUPPLY, as nothing is signed on top of it. It counts again once two keys that stay sign it. It also counts again when a peer sends a copy of the same version, by its time stamp and digest, that two active keys signed, as when two members co-signed its proposal: that copy takes its place without a renewal. The board keys spork takes no such copy.

gridspork-renew proposes every spork the node holds again with its data unchanged, including one that a switched-off key signed, but only once its type is named. Without it the command refuses all: Renewing refused, nothing was proposed: the MINT_SUPPLY spork is signed by <16 hex> (switched off) and <16 hex>; give --switched-off MINT_SUPPLY to renew it. Give --switched-off <TYPE> once for each such type. Each such spork is shown as Stored MINT_SUPPLY is signed by <16 hex> (switched off) and <16 hex>, made at <time>, and counts for nothing until it is signed again. A node run without the hidden --preview switch hands out no storage, ledger or communication spork, so the command renews those only on a node started with it.

gridspork-cosign co-signs a renewal of such a spork only on a node that stores it, and only with --switched-off <TYPE>. It refuses a proposal that changes the data, as two stolen switched-off keys can forge the stored spork; both refusals are in When co-signing fails. Both members sign with keys active now, so the renewed spork counts again once the second signature holds. Data that only switched-off keys ever signed comes back through util spork-db sign.

The steps

  1. Member A runs hedgehog cli gridspork-renew -k <key of A>. The command reads every spork the node holds, checks each stored head and prints all their data before it signs. It signs each spork with its data unchanged and hands it back; for each it prints Accepted and the proposal, with its digest and expires. If any stored spork cannot be signed, nothing is proposed and the command prints Renewing refused, nothing was proposed: <message>. If the node holds no spork, it prints No sporks to renew.
  2. Member B runs hedgehog cli gridspork-cosign -k <key of B> <digest> <digest> … with those digests, each 128 lower-case hex characters, and --switched-off <TYPE> for each type that needs it.

While a proposal that changes a type waits for its co-signature, the node refuses the renewal of that type with 409. For that type the command prints Conflict and The spork does not follow on the stored spork and the proposal held, still proposes the other types, and ends with exit code 1. A change proposal past its 60 minutes does not block a renewal.

Renew on a node that holds the newest version of every type: before renewing, compare gridspork-log on it and on a second node. A renewal made on a node that has not taken a change yet renews the version before that change. Nodes that hold the change refuse the renewal. A node that took the renewal gives it up for the change when the two were stamped at most 60 minutes apart; further apart, each node keeps the one it holds. A renewal of the board keys spork gives way to a change of it however far apart the two were stamped.

In the source

  • application/src/main/java/org/unigrid/hedgehog/command/cli/GridSporkRenew.java: gridspork-renew
  • application/src/main/java/org/unigrid/hedgehog/command/cli/GridSporkCosign.java: the co-sign command and --switched-off
  • application/src/main/java/org/unigrid/hedgehog/command/cli/spork/SporkProposal.java: checking and showing a spork before signing
  • application/src/main/java/org/unigrid/hedgehog/client/rest/SporkClient.java: the checks on what the node hands out