Documentation
¶
Overview ¶
Package opentimestamps implements the AnchorProvider interface using the OpenTimestamps calendar server HTTP API (https://opentimestamps.org).
Library choice (2026-05-03) ¶
github.com/opentimestamps/go-opentimestamps does not exist (repository not found on GitHub). The `ots` CLI binary is also absent from the current environment. This implementation therefore calls the calendar server HTTP API directly, which is well-defined and stable:
- Anchor: POST <calendar>/digest with 32 raw bytes → pending OTS receipt bytes
- Verify: GET <calendar>/timestamp/<hash_hex> → 200 = upgraded (Bitcoin confirmed); 404 = still pending; 5xx = transient; 4xx = hard error
The raw calendar receipts are stored as base64 in the ProofData JSON so that a future OTS binary parser (needed for extracting the calendar-tree commitment for production-grade inclusion proofs) can reprocess them without re-anchoring. For upgrade checking, we use the submitted hash hex as the lookup key; this works with the standard OTS calendar server API.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// CalendarServers is the list of OTS calendar server base URLs to submit to.
// Multiple servers provide redundancy. At least one is required.
CalendarServers []string `json:"calendar_servers"`
// HTTPTimeout is the per-request timeout. Defaults to 30s when zero.
HTTPTimeout time.Duration `json:"http_timeout,omitempty"`
}
Config holds configuration for the OpenTimestamps provider.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider implements providers.AnchorProvider via OTS calendar server HTTP API.
func NewProvider ¶
NewProvider creates a new OpenTimestamps provider with the given config. Returns an error if no calendar servers are configured.
func (*Provider) Anchor ¶
Anchor submits the Merkle root to all configured calendar servers.
ExternalID is set to root.Hex (the submitted hash). ProofData is a JSON blob containing the raw calendar receipts from each successful submission.
Returns an error only if ALL calendar servers fail. Partial success (at least one calendar accepts the submission) returns a valid Anchor.
func (*Provider) Verify ¶
func (p *Provider) Verify(ctx context.Context, anchor providers.Anchor) (providers.Verification, error)
Verify polls the calendar servers recorded in anchor.ProofData for Bitcoin confirmation status. Implements the swallow-transient-errors contract (§ 3.5c):
Network errors and 5xx responses are swallowed: returned as a successful Verification with Swallowed=true, ErrorMessage populated, and Confirmation unchanged from anchor.Confirmation.
4xx responses that semantically reject the proof are returned as errors (hard errors that abort the parent step).
If any calendar returns an upgraded proof (HTTP 200), the Confirmation advances to ConfirmationConfirmed.
404 responses indicate the proof is not yet upgraded (still pending); this is informative, not an error, and does not set Swallowed.
Source Files