Documentation
¶
Overview ¶
Package entropy is a thin client for the Truestamp entropy observations JSON:API surface (GET /api/json/entropy_observations and /entropy_observations/:id).
An entropy observation is a witness: a public random value Truestamp captured from an independent source (a NIST Randomness Beacon pulse, a Stellar ledger close, a Bitcoin block) together with the moment it was captured. Item submission commits the newest observation per source into the item's metadata, which is what opens the submitted-after edge of the submission window: the item cannot have been submitted before a value that did not yet exist. Each observation is also a proof subject in its own right (`proofs get --type entropy_*`), and this package is the discovery path to the ids those proofs are asked for by.
Two things the server does not offer, worked around here the way internal/blocks does:
- There is no /latest route: latest is a sort plus a limit of one.
- There is no by-hash route: a hash lookup is filter[entropy_hash], and the hex shape is validated 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 entropy observation matches that hash")
ErrAmbiguousHash is returned when a by-hash lookup matches more than one row. The server does not assume hash uniqueness, so this is reported rather than resolved by picking one.
var Sources = []string{"entropy_nist", "entropy_stellar", "entropy_bitcoin"}
Sources is the closed set of entropy sources, in the order the CLI lists them. They are the wire names, identical to the proof subject types `proofs get --type` takes, so one vocabulary names both.
Functions ¶
func ValidateHash ¶
ValidateHash rejects anything that is not exactly 64 lowercase hex characters, before it can reach filter[entropy_hash].
func ValidateSource ¶
ValidateSource rejects a --source value outside Sources.
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 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 {
Source string
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. Source empty means every source; otherwise it must be one of Sources. The paging fields are the ones every keyset-paged list shares (jsonapi.SetPageQuery).
type Observation ¶
type Observation struct {
ID string `json:"id"`
Source string `json:"source"`
State string `json:"state"`
EntropyHash string `json:"entropy_hash"`
ObservationHash string `json:"observation_hash"`
MetadataHash string `json:"metadata_hash"`
SigningKeyID string `json:"signing_key_id"`
Signature string `json:"signature"`
CaptureMethod string `json:"capture_method"`
SourcePublishedAt string `json:"source_published_at"`
InsertedAt string `json:"inserted_at"`
BlockID string `json:"block_id,omitempty"`
Entropy map[string]any `json:"entropy"`
Metadata map[string]any `json:"metadata"`
}
Observation is the public shape of one entropy observation. Entropy is the source's own record under its own field names (a Stellar ledger's sequence and closed_at, a NIST pulse's index, a Bitcoin block's height) and is rendered as published, never renamed. Its numbers are decoded as json.Number so a ledger sequence is never re-printed as a float.
func ByHash ¶
ByHash fetches one observation by its 64-hex entropy hash. There is no by-hash route, so this filters; see the package doc.
Source Files