REST: legacy chain
Three endpoints under /bootstrap read the legacy chain snapshot: the facts about the
snapshot itself, the balance of a legacy address and its dated history. They are part of the
REST interface and need the bearer token like every other endpoint. They change nothing.
The snapshot is the file bootstrap.dat in the data directory of the node. The --snapshot option belongs to the
bootstrap commands and does not move the file a running node reads. A daemon opens an existing file as it
starts, to tell whether it needs the snapshot of its release; a snapshot it downloads is opened on the first request
that asks for it. The file is opened again on the next request after it was replaced, so a snapshot installed by
hedgehog bootstrap fetch is used without a restart. A file the node refused is judged again after it was
replaced, or after the node took a longer chain of board keys, which may hold the key that signed it. Without a
file, or with one that fails its checks, every endpoint on this page answers 503. A file that is removed after it
was opened keeps being answered from until another file takes its place.
Addresses. A legacy address is written the way the legacy chain wrote it: base58 with a checksum, one version byte of 40 and a 20-byte hash. An address that is longer than 50 characters is refused before it is decoded. A character outside base58, a wrong checksum, another version byte or another hash length is answered with 400 and an empty body.
Amounts and times. An amount is a JSON number with up to eight decimals. A time is an ISO 8601 instant. A transaction id and the tip hash are 64 lower-case hex characters, in the order the legacy daemon displayed them.
GET /bootstrap
Facts about the snapshot, the same as hedgehog bootstrap info prints.
| Answer | Meaning |
|---|---|
| 200 | The facts below |
| 503 | The node holds no usable snapshot |
| Field | Meaning |
|---|---|
tipHash, tipHeight |
The newest block of the legacy chain in the snapshot |
addressCount |
The addresses the snapshot holds, also those that hold nothing now |
entryCount |
The entries of all address histories |
transactionCount |
The transactions the entries refer to |
totalUnspent |
The coins that are unspent at the tip |
zerocoinMinted |
The coins minted into the zerocoin pool, which are not credited to an address |
built |
When the snapshot was built |
signature |
SIGNED when a key that was ever a board key signed it, UNSIGNED when it carries no signature. A snapshot whose signature does not verify, or that ends in bytes that are no whole signature, is refused and so never reported |
{
"tipHash": "00000000…",
"tipHeight": 3172666,
"addressCount": 28431,
"entryCount": 16799121,
"transactionCount": 1650000,
"totalUnspent": 15900032.04557988,
"zerocoinMinted": 1200.0,
"built": "2026-09-30T08:12:44Z",
"signature": "SIGNED"
}
GET /bootstrap/address/{address}
The balance of one legacy address.
| Answer | Meaning |
|---|---|
| 200 | address, balance and transactionCount |
| 400 | The address is not a legacy address, see above |
| 404 | The snapshot does not hold the address and no mint is promised to it |
| 503 | The node holds no usable snapshot |
| Field | Meaning |
|---|---|
address |
The address as it was asked for |
balance |
What the snapshot says the address holds, plus the mints that are promised to it and not yet made |
transactionCount |
The entries in the history of the address in the snapshot; mints that are only promised are not counted |
Mints that wait. The MINT_STORAGE spork lists amounts that are minted to an address at a height, see
Ledger sporks. The height of the legacy chain is the tip of the snapshot. A mint whose height is
above it has not happened yet, and the balance includes it, rounded down to eight decimals. Only the sporks that
count are summed, not those of a key the board has switched off. An address that has only such a mint, and no
history, is answered with a balance and transactionCount 0 instead of 404.
{
"address": "UXq3…",
"balance": 250.5,
"transactionCount": 4
}
GET /bootstrap/address/{address}/transactions
The dated history of one legacy address, oldest first.
| Parameter | Meaning |
|---|---|
offset |
The first entry to return, 0 by default; a negative number counts as 0 |
limit |
At most this many entries, 100 by default and never more than 1000; a negative number counts as 0 |
| Answer | Meaning |
|---|---|
| 200 | A list of entries, empty when the address has none or the snapshot does not hold it |
| 400 | The address is not a legacy address, see above |
| 503 | The node holds no usable snapshot |
An address that the snapshot does not hold is answered with an empty list, not with 404 as the balance is. Mints that are only promised are not listed.
| Field | Meaning |
|---|---|
transaction |
The id of the transaction |
time |
The time of the block that holds it |
height |
The height of that block |
amount |
The coins moved |
kind |
RECEIVED, SENT, MINED or STAKED |
[
{
"transaction": "9c1e…",
"time": "2021-03-14T09:26:53Z",
"height": 412345,
"amount": 100.0,
"kind": "RECEIVED"
}
]
To read all of a long history, repeat the call with offset raised by the number of entries the last answer held
until it comes back with fewer than limit.
The same address in the ledger
On a node started with --preview --ledger, GET /ledger/account/{address} also takes a legacy address, and
answers what the ledger holds for it: the balance that mints have put on it, what a claim would move now and who
claimed it, see REST: ledger. The two answers differ on purpose. /bootstrap tells what the legacy
chain held, /ledger what the ledger holds for the address.
In the source
application/src/main/java/org/unigrid/hedgehog/server/rest/BootstrapResource.java: the three endpoints.application/src/main/java/org/unigrid/hedgehog/model/bootstrap/SnapshotReader.java: the lookups in the snapshot file.application/src/main/java/org/unigrid/hedgehog/model/bootstrap/BootstrapSnapshot.java: opens the file when it is first asked for and again when it was replaced, and judges a refused file again under a longer chain of board keys.application/src/main/java/org/unigrid/hedgehog/model/bootstrap/LegacyAddress.java: how an address is checked.application/src/main/java/org/unigrid/hedgehog/model/bootstrap/PendingMints.java: the mints that wait.application/src/main/java/org/unigrid/hedgehog/model/bootstrap/ChainHeight.java: the height the mints are compared with.