Documentation
¶
Overview ¶
Package external fetches supplementary data from public blockchains (Stellar Horizon, Bitcoin block explorers) to corroborate proofs against real-world public records.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( BlockstreamMainnetURL = "https://blockstream.info/api" BlockstreamTestnetURL = "https://blockstream.info/testnet/api" )
BlockstreamMainnetURL / BlockstreamTestnetURL are the Blockstream API endpoints consulted by VerifyBitcoinBlock. Exposed as vars so tests can redirect them; do not mutate in production code.
var ( HorizonPublicURL = "https://horizon.stellar.org" HorizonTestnetURL = "https://horizon-testnet.stellar.org" )
HorizonPublicURL / HorizonTestnetURL are the Stellar Horizon endpoints consulted by VerifyStellar. Exposed as vars so tests can point them at an httptest server; do not mutate in production code.
var NISTBeaconURL = "https://beacon.nist.gov/beacon/2.0"
NISTBeaconURL is the NIST Randomness Beacon v2.0 base URL. Exposed as a var so tests can redirect it; do not mutate in production code.
Functions ¶
func VerifyKeyring ¶
VerifyKeyring checks that all signing keys in the proof match the published keyring.
Trust model: the keyring's authenticity is rooted entirely in the TLS chain presented by keyringURL. There is no in-band signature over the keyring payload itself, so every key in the returned document is only as trustworthy as the URL you configured. In particular:
- Use https:// with a host whose certificate chain you trust (an attacker able to mint a valid cert for the host — via DNS/BGP hijack, a rogue CA, or a compromised certificate — can substitute signing keys and every downstream signature will validate against their key).
- Configure --keyring-url (or the TRUESTAMP_KEYRING_URL env var, or the keyring_url setting in config.toml) from a source you trust — e.g. official Truestamp docs — not from a bundle authored by the same party whose proof you are verifying.
- The CLI enforces TLS chain validation (InsecureSkipVerify is never set) and does not follow cross-host redirects that strip TLS.
A future revision may add pinning of the keyring payload's hash or a cosign/Sigstore signature over the keyring document itself. Until then, treat keyring-url as a root of trust that deserves the same care as a CA root.
Types ¶
type BitcoinBlockHeader ¶ added in v0.6.0
BitcoinBlockHeader is the CLI-facing return shape for GetBitcoinBlockHeader.
func GetBitcoinBlockHeader ¶ added in v0.6.0
func GetBitcoinBlockHeader(blockHash, network string) (*BitcoinBlockHeader, bool, error)
GetBitcoinBlockHeader fetches a Bitcoin block header from Blockstream by block hash. Returns (nil, skipped=true, nil) for regtest (no public API).
type BitcoinResult ¶
type BitcoinResult struct {
Height int
Timestamp string // ISO 8601 block timestamp from Blockstream
}
BitcoinResult holds the verification result from the Blockstream API.
func VerifyBitcoinBlock ¶
func VerifyBitcoinBlock(blockHash, network string) (*BitcoinResult, bool, error)
VerifyBitcoinBlock checks the Blockstream API to confirm a Bitcoin block exists. Returns the block height and timestamp, or an error. For regtest, returns a skip indicator.
type KeyringKey ¶
type KeyringKey struct {
KeyID string `json:"key_id"`
PublicKey string `json:"public_key"`
Sequence int `json:"sequence"`
Active bool `json:"active"`
}
KeyringKey is a single entry in the keyring.
type KeyringResponse ¶
type KeyringResponse struct {
Version string `json:"version"`
Keys []KeyringKey `json:"keys"`
}
KeyringResponse is the shape of /.well-known/keyring.json.
type NISTPulse ¶ added in v0.6.0
type NISTPulse struct {
ChainIndex int `json:"chainIndex"`
PulseIndex int `json:"pulseIndex"`
OutputValue string `json:"outputValue"`
TimeStamp string `json:"timeStamp"`
Version string `json:"version"`
}
NISTPulse holds the minimum set of NIST Beacon pulse fields the CLI byte-compares against entropy subject data. Signature-chain verification is not performed: the Truestamp service stores only these five fields, so the entropy subject hash it signed is already over the same slice of data we compare here.
func GetNISTPulse ¶ added in v0.6.0
GetNISTPulse fetches a specific pulse from the NIST Randomness Beacon v2.0 API at /chain/{chainIndex}/pulse/{pulseIndex}.
NIST Beacon reliability caveat (per truestamp-v2 docs): during US federal shutdowns the beacon may stop publishing new pulses and repeat the last pulse indefinitely. Callers that care about freshness should apply their own staleness policy on top of this fetch.
type StellarLedger ¶ added in v0.6.0
StellarLedger is the CLI-facing return shape for GetStellarLedger.
func GetStellarLedger ¶ added in v0.6.0
func GetStellarLedger(sequence int, network string) (*StellarLedger, error)
GetStellarLedger fetches a specific ledger from Stellar Horizon at /ledgers/{sequence}. The caller compares returned hash + closed_at against the entropy subject data; network selection (testnet|public) is the caller's responsibility.
type StellarResult ¶
type StellarResult struct {
Ledger int
Timestamp string // ISO 8601 ledger close timestamp from Horizon
}
StellarResult holds the verification result from the Stellar Horizon API.
func VerifyStellar ¶
func VerifyStellar(transactionHash, expectedMemoHash, network string, expectedLedger int) (*StellarResult, error)
VerifyStellar checks the Stellar Horizon API to confirm the transaction exists, the memo matches, and the ledger number matches the expected value. Returns the ledger number, the transaction timestamp, or an error.
Source Files