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, format string) ([]byte, error)
- func GenerateCtx(ctx context.Context, apiURL, apiKey, team, id, format string) ([]byte, 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
GenerateCtx requests a proof bundle from the Truestamp API for the given subject ID. The server auto-detects item (ULID) vs entropy (UUIDv7) from the ID format. format should be "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 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 string `json:"t"` // "stellar" or "bitcoin"
Network string `json:"net"` // "testnet", "public", "mainnet", "regtest"
// 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 (stellar or bitcoin). Each has an epoch Merkle proof (ep) linking the block hash to the committed value.
func FindCommitByType ¶
func FindCommitByType(commits []ExternalCommit, typ string) *ExternalCommit
FindCommitByType returns the first external commitment with the given type, or nil.
type IDType ¶
type IDType string
IDType represents the detected ID format.
func DetectIDType ¶
DetectIDType determines whether an ID is a ULID (item) or UUIDv7 (entropy).
type ProofBundle ¶
type ProofBundle struct {
Version int `json:"v"`
Type string `json:"-"` // derived from Subject.Source during parsing
Timestamp string `json:"ts"`
PublicKey string `json:"pk"`
Signature string `json:"sig"`
// Typed access to proof contents (populated during parsing)
Subject Subject `json:"-"`
Block Block `json:"-"`
Commitments []ExternalCommit `json:"-"`
InclusionProof string `json:"-"` // base64url compact Merkle proof
// Raw JSON preserved for JCS canonicalization (extracted from subject.data)
RawData json.RawMessage `json:"-"`
}
ProofBundle is the top-level proof structure (v1 compact format).
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.
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) IsEntropy ¶
func (b *ProofBundle) IsEntropy() bool
IsEntropy returns true if this proof bundle is for an entropy observation.
func (*ProofBundle) MarshalJSON ¶
func (b *ProofBundle) MarshalJSON() ([]byte, error)
MarshalJSON produces the compact JSON format from a parsed ProofBundle. Used when sending a CBOR-decoded proof to the API as JSON.
type Subject ¶
type Subject struct {
Source string `json:"src"`
ID string `json:"id"`
Data json.RawMessage `json:"d"`
MetadataHash string `json:"mh"`
SigningKeyID string `json:"kid"`
}
Subject represents the unified subject within a proof bundle. For item proofs, Source is "item" and Data contains claims. For entropy proofs, Source is the entropy source (e.g., "nist_beacon").
Source Files