providers

type Anchor struct {
	ProviderName string
	AnchoredAt   time.Time
	ExternalID   string            // provider's anchor reference (Bitcoin tx hash, git commit sha, Rekor entry ID, etc.)
	ProofData    []byte            // provider-specific; opaque to caller; stored in audit_anchors.proof_data
	Confirmation ConfirmationLevel // pending | confirmed | finalized
}

type AnchorProvider interface {
	// Name returns the provider's stable identifier (e.g. "opentimestamps", "git").
	Name() string

	// Anchor submits the Merkle root to the external anchor target and returns
	// an Anchor struct. The returned Confirmation is always ConfirmationPending
	// immediately after anchoring.
	Anchor(ctx context.Context, root MerkleRoot) (Anchor, error)

	// Verify polls the external target for the current confirmation state of a
	// previously-created Anchor. Follows the swallow-transient-errors contract
	// described above.
	Verify(ctx context.Context, anchor Anchor) (Verification, error)

	// Cost returns the cost model for the given number of anchors (for budgeting).
	Cost(numAnchors int) Cost
}

type ConfirmationLevel string

type Cost struct {
	PerAnchorUSDCents int64
	Notes             string
}

type MerkleRoot struct {
	Hex string // hex-encoded sha256 (64 lowercase chars)
}

type Verification struct {
	Provider     string
	Confirmation ConfirmationLevel
	UpdatedAt    time.Time
	Swallowed    bool   // true if a transient error occurred but state was preserved; no error returned
	ErrorMessage string // populated when Swallowed=true; describes the transient error
}