Documentation
¶
Overview ¶
Package blocks is a thin client for the Truestamp Blocks JSON:API surface (GET /api/json/blocks, /blocks/:id).
A block is the full signed record: Merkle root, state, signature, key id and chain links. The same block projected to four public fields is a *beacon*, served by internal/beacons. They are two views of one row, and they are separate here for the same reason they are separate commands: only finalized or committed blocks project as beacons, so "the head block" and "the most recent beacon" are different questions most of the time — the chain advances about once a minute and the head is routinely not yet finalized.
Two things the server does not offer, and that this package therefore works around rather than assumes:
- There is no /blocks/latest or /blocks/genesis route, though the Ash actions exist. Both are a sort plus a limit of one.
- There is no by-hash route. Addressing by hash goes through filter[block_hash], which — unlike the beacons by-hash action — has NO server-side shape guard, and an unguarded cast raises a Ecto.Query.CastError, a 500 that leaks SQL. So the hex shape is validated here, before the request is sent.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrForbidden = jsonapi.ErrForbidden ErrNotFound = jsonapi.ErrNotFound ErrBadRequest = jsonapi.ErrBadRequest ErrRateLimited = jsonapi.ErrRateLimited ErrServer = jsonapi.ErrServer )
var ErrAmbiguousHash = errors.New("more than one block matches that hash")
ErrAmbiguousHash is returned when a by-hash lookup matches more than one row. The server does not assume block-hash uniqueness, so this is reported rather than resolved by picking one.
Functions ¶
func ValidateHash ¶
ValidateHash rejects anything that is not exactly 64 lowercase hex characters, before it can reach filter[block_hash].
func ValidateUUIDv7 ¶
ValidateUUIDv7 rejects an id that is not a UUIDv7.
Types ¶
type APIError ¶
The transport, the class sentinels and APIError live in internal/jsonapi; these aliases keep this client's surface stable for the commands that errors.Is its classes.
type Block ¶
type Block struct {
ID string `json:"id"`
BlockHash string `json:"block_hash"`
MerkleRoot string `json:"merkle_root"`
State string `json:"state"`
PreviousBlockID string `json:"previous_block_id"`
PreviousBlockHash string `json:"previous_block_hash"`
SigningKeyID string `json:"signing_key_id"`
Signature string `json:"signature"`
InsertedAt string `json:"inserted_at"`
}
Block is the subset of a block's public attributes the CLI renders. The server pins exactly eleven public attributes with a test; these are the ones that identify a block and place it in the chain.
There is deliberately no Height field. block_height is a runtime COUNT(*) calculation, explicitly non-sortable and non-filterable, and withheld from the wire. A block is addressed by UUIDv7, which is also its ordering handle.
func ByHash ¶
ByHash fetches one block by its 64-hex block hash. There is no by-hash route, so this filters; see the package doc for why the shape is validated here first.
func Genesis ¶
Genesis fetches the first block, the trust root every chain walk terminates at. It is identifiable by id == previous_block_id.
type Config ¶
The transport, the class sentinels and APIError live in internal/jsonapi; these aliases keep this client's surface stable for the commands that errors.Is its classes.
type ListOptions ¶
type ListOptions struct {
Limit int
After string // continue forward from a Page.NextCursor
Before string // continue backward from a Page.PrevCursor
OldestFirst bool // walk from the beginning instead of the newest row
Count bool
}
ListOptions configures a list request; the paging fields are the ones every keyset-paged list shares (jsonapi.SetPageQuery).
Source Files