Documentation
¶
Overview ¶
Package proof parses, downloads, and generates Truestamp proof bundles in both JSON and CBOR wire formats. Proofs are the self-contained artefacts consumers receive from the API; this package handles only serialization and I/O — cryptographic verification lives in internal/verify.
Index ¶
- func Download(rawURL string) ([]byte, error)
- func DownloadCtx(ctx context.Context, rawURL string) ([]byte, error)
- func FileSize(filename string) int64
- func FileSizeFromData(data []byte) int64
- func Generate(apiURL, apiKey, team, id, subjectType, format string) ([]byte, error)
- func GenerateCtx(ctx context.Context, apiURL, apiKey, team, id, subjectType, format string) ([]byte, error)
- func InspectBundleType(data []byte) (ptype.Code, error)
- func IsCBORProof(data []byte) bool
- type Block
- type ExternalCommit
- type IDType
- type ProofBundle
- type Subject
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Download ¶
Download fetches a proof bundle from a URL using context.Background. Prefer DownloadCtx when a cancellable context is available.
func DownloadCtx ¶ added in v0.3.0
DownloadCtx is the context-aware variant of Download. Honours ctx for cancellation (e.g. Ctrl-C while a proof is streaming).
func FileSizeFromData ¶
FileSizeFromData returns the byte length of proof data.
func Generate ¶
Generate calls GenerateCtx with context.Background.
func GenerateCtx ¶ added in v0.3.0
func GenerateCtx(ctx context.Context, apiURL, apiKey, team, id, subjectType, format string) ([]byte, error)
GenerateCtx requests a proof bundle from the Truestamp API for the given subject ID. subjectType MUST be one of the six canonical values on the server's /proof/generate type enum (empty string omits the field, which the server rejects under the post-cutover schema — callers should always pass an explicit value):
item | entropy_nist | entropy_stellar | entropy_bitcoin | block | beacon
"auto" and bare "entropy" were removed when the server cut over to the strict enum alongside t=11 beacon support. Use the matching subtype.
format is "json" or "cbor". Returns raw bytes ready to write to a file (pretty JSON or decoded CBOR binary). ctx cancels the in-flight request.
func InspectBundleType ¶ added in v0.6.0
InspectBundleType returns the subject type code `t` of a proof bundle encoded as either pretty JSON or deterministic CBOR. Used by downloaders to pick a filename stem from the authoritative server-returned type.
func IsCBORProof ¶
IsCBORProof checks for CBOR self-describing tag (0xd9d9f7, RFC 8949 tag 55799).
Types ¶
type Block ¶
type Block struct {
ID string `json:"id"`
PreviousBlockHash string `json:"ph"`
MerkleRoot string `json:"mr"`
MetadataHash string `json:"mh"`
SigningKeyID string `json:"kid"`
}
Block represents the single block in the proof.
type ExternalCommit ¶
type ExternalCommit struct {
Type ptype.Code `json:"t"`
Network string `json:"net"` // Stellar: "testnet"|"public" ; Bitcoin: "regtest"|"testnet"|"mainnet"
// Epoch Merkle proof (base64url compact binary)
EpochProof string `json:"ep"`
// Stellar fields
TransactionHash string `json:"tx,omitempty"`
MemoHash string `json:"memo,omitempty"`
Ledger int `json:"l,omitempty"`
Timestamp string `json:"ts,omitempty"`
// Bitcoin fields
OpReturn string `json:"op,omitempty"`
RawTxHex string `json:"rtx,omitempty"`
TxoutproofHex string `json:"txp,omitempty"`
BlockMerkleRoot string `json:"bmr,omitempty"`
BlockHeight int `json:"h,omitempty"`
}
ExternalCommit represents a commitment entry in the proof bundle. Type is an integer code from ptype (CommitmentStellar=40, CommitmentBitcoin=41). Each commitment carries an epoch Merkle proof (ep) linking the block hash to the committed value (Stellar: memo, Bitcoin: OP_RETURN payload).
func FindCommitByType ¶
func FindCommitByType(commits []ExternalCommit, t ptype.Code) *ExternalCommit
FindCommitByType returns the first external commitment with the given type code, or nil.
type IDType ¶
type IDType string
IDType is the syntactic shape of a subject id. It is NOT the subject's semantic kind (item / entropy / block / beacon) — the server decides that from the id on /proof/generate. Use DetectIDType for pre-flight validation and for sanity-checking positional args; rely on the server's returned `t` for authoritative subject labelling.
func DetectIDType ¶
DetectIDType returns the syntactic shape of id. Returns an error for values that are neither a valid ULID nor a parseable UUID.
type ProofBundle ¶
type ProofBundle struct {
Version int `json:"v"`
T ptype.Code `json:"t"`
Timestamp string `json:"ts"`
PublicKey string `json:"pk"`
Signature string `json:"sig"`
// Subject is nil for block-like subjects (t ∈ {10, 11}). For all other
// subject types it is non-nil after a successful parse.
Subject *Subject `json:"-"`
Block Block `json:"-"`
Commitments []ExternalCommit `json:"-"`
// InclusionProof is "" for block-like subjects and non-empty otherwise.
InclusionProof string `json:"-"` // base64url compact Merkle proof
// RawData is the subject-data JSON preserved byte-for-byte for JCS.
// Empty for block-like subjects.
RawData json.RawMessage `json:"-"`
}
ProofBundle is the top-level compact Truestamp proof structure (bundle version `v` is 1). See `docs/PROOF_FORMAT.md` (authoritative spec) and `docs/PROOF_FORMAT_IMPLEMENTERS_GUIDE.md` (cross-implementation guide) in the truestamp-v2 reference repo.
The top-level integer field `t` discriminates subject types:
10 block (no Subject, no InclusionProof) 11 beacon (no Subject, no InclusionProof — same shape as block) 20 item 30 entropy_nist 31 entropy_stellar 32 entropy_bitcoin
func Parse ¶
func Parse(filename string) (*ProofBundle, error)
Parse reads and parses a proof JSON file, preserving raw JSON for JCS.
func ParseBytes ¶
func ParseBytes(data []byte) (*ProofBundle, error)
ParseBytes parses a proof from raw bytes. Detects CBOR format (self- describing tag 0xd9d9f7) and falls back to JSON parsing. Enforces:
- v == 1
- t ∈ {10, 11, 20, 30, 31, 32}
- cx non-empty, every cx[i].t ∈ {40, 41}
- t ∈ {10, 11} (block-like): s absent, ip absent
- t ∉ {10, 11}: s present with id/d/mh/kid, ip present and non-empty
func ParseCBOR ¶
func ParseCBOR(data []byte) (*ProofBundle, error)
ParseCBOR decodes a CBOR proof bundle into a ProofBundle. The output is structurally identical to what ParseBytes produces from JSON.
func (*ProofBundle) IsBeacon ¶ added in v0.6.0
func (b *ProofBundle) IsBeacon() bool
IsBeacon returns true if this bundle is a beacon subject (t=11). Beacon bundles are structurally identical to block bundles but carry a distinct type code for domain separation — their signatures differ from the block bundle of the same block because `t` is in the signing payload.
func (*ProofBundle) IsBlock ¶ added in v0.6.0
func (b *ProofBundle) IsBlock() bool
IsBlock returns true if this bundle is a plain block subject (t=10). Does NOT include beacon (t=11); use IsBlockLike for that.
func (*ProofBundle) IsBlockLike ¶ added in v0.6.0
func (b *ProofBundle) IsBlockLike() bool
IsBlockLike returns true if this bundle is either a block (t=10) or a beacon (t=11). Use this in verification-pipeline guards that skip subject / inclusion-proof / subject-hash-derivation steps — those are shape concerns and beacon proofs have the same shape as block proofs.
func (*ProofBundle) IsEntropy ¶
func (b *ProofBundle) IsEntropy() bool
IsEntropy returns true if this bundle is an entropy subject (t in {30,31,32}).
func (*ProofBundle) IsItem ¶ added in v0.6.0
func (b *ProofBundle) IsItem() bool
IsItem returns true if this bundle is an item subject (t=20).
func (*ProofBundle) MarshalCBOR ¶ added in v0.5.0
func (b *ProofBundle) MarshalCBOR() ([]byte, error)
MarshalCBOR produces the canonical CBOR representation of the proof bundle. Byte-valued fields (`pk`, `sig`, hashes, epoch/inclusion proofs) are emitted as CBOR major-type-2 byte strings; identifier fields (ULID, UUIDv7, timestamps) remain text. The subject data (`s.d`) is decoded back from its preserved raw JSON and encoded as a nested CBOR structure. `t` is emitted as a CBOR integer at the top level and per commitment entry.
Round-trip guarantee: `cbor → Parse → MarshalCBOR` is byte-stable for inputs that are themselves deterministically encoded. Non-deterministic source CBOR is normalized on the first round trip.
func (*ProofBundle) MarshalJSON ¶
func (b *ProofBundle) MarshalJSON() ([]byte, error)
MarshalJSON produces the compact JSON wire format from a parsed ProofBundle. Subject and InclusionProof are omitted for block-like subjects (t ∈ {10, 11}). Used when sending a CBOR-decoded proof to the API as JSON.
type Subject ¶
type Subject struct {
ID string `json:"id"`
Data json.RawMessage `json:"d"`
MetadataHash string `json:"mh"`
SigningKeyID string `json:"kid"`
}
Subject represents the unified subject within a non-block proof bundle. For item proofs (T=20), Data contains the claims map. For entropy subjects (T in {30,31,32}), Data contains the entropy observation. The source is carried in the top-level ProofBundle.T field; no per- subject `src` discriminator is emitted.
Source Files
Directories