initial scaffold

- module layout: cmd/mithril-go, internal/{aggregator,artifact,verify,networks}
- aggregator REST client, list command working against mainnet
- download/extract/verify stubbed
- no deps yet, pure stdlib

internal/aggregator/client.go

@@ -0,0 +1,125 @@
+// Package aggregator is a thin HTTP client for the Mithril aggregator REST API.
+//
+// Only the handful of endpoints needed for client-side snapshot workflows are
+// exposed. Authentication is not required for the read paths used here.
+package aggregator
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type Client struct {
+	baseURL string
+	http    *http.Client
+}
+
+func New(baseURL string) *Client {
+	return &Client{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+// CardanoDBSnapshot is the server-reported shape for /artifact/cardano-database/{hash}.
+// Field set is trimmed to what the client actually consumes — full schema documented
+// at https://mithril.network/doc/aggregator-api/.
+type CardanoDBSnapshot struct {
+	Hash                  string                   `json:"hash"`
+	MerkleRoot            string                   `json:"merkle_root"`
+	Network               string                   `json:"network"`
+	Beacon                Beacon                   `json:"beacon"`
+	CertificateHash       string                   `json:"certificate_hash"`
+	TotalDBSizeUncompressed uint64                 `json:"total_db_size_uncompressed"`
+	Digests               LocationList             `json:"digests"`
+	ImmutablesAncillary   LocationList             `json:"immutables"`
+	ImmutablesIncremental *IncrementalImmutables   `json:"immutables_incremental,omitempty"`
+	CreatedAt             time.Time                `json:"created_at"`
+}
+
+type Beacon struct {
+	Epoch           uint64 `json:"epoch"`
+	ImmutableFileNumber uint64 `json:"immutable_file_number"`
+}
+
+type LocationList struct {
+	Size      uint64       `json:"size"`
+	Locations []LocationAlt `json:"locations"`
+}
+
+// LocationAlt is a best-of alternative; Mithril returns a typed-discriminated object.
+type LocationAlt struct {
+	Type string `json:"type"` // e.g. "cloud_storage", "ipfs"
+	URI  string `json:"uri"`
+}
+
+type IncrementalImmutables struct {
+	AverageSize uint64       `json:"average_size"`
+	Locations   []LocationAlt `json:"locations"`
+}
+
+// Certificate is the server-reported shape for /certificate/{hash}.
+// Kept minimal; STM verification reads what it needs from the raw JSON later.
+type Certificate struct {
+	Hash            string          `json:"hash"`
+	PreviousHash    string          `json:"previous_hash"`
+	Epoch           uint64          `json:"epoch"`
+	SignedMessage   string          `json:"signed_message"`
+	ProtocolMessage json.RawMessage `json:"protocol_message"`
+	Multisignature  json.RawMessage `json:"multi_signature"`
+	GenesisSignature string         `json:"genesis_signature,omitempty"`
+}
+
+func (c *Client) get(ctx context.Context, path string, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Accept", "application/json")
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("aggregator GET %s: %w", path, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return fmt.Errorf("aggregator GET %s: status %d: %s", path, resp.StatusCode, string(body))
+	}
+	if out == nil {
+		return nil
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+// ListCardanoDBSnapshots returns the sorted-newest-first list of cardano-database snapshots.
+func (c *Client) ListCardanoDBSnapshots(ctx context.Context) ([]CardanoDBSnapshot, error) {
+	var out []CardanoDBSnapshot
+	if err := c.get(ctx, "/artifact/cardano-database", &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// GetCardanoDBSnapshot fetches details for a single snapshot by hash (or "latest").
+func (c *Client) GetCardanoDBSnapshot(ctx context.Context, hash string) (*CardanoDBSnapshot, error) {
+	var out CardanoDBSnapshot
+	if err := c.get(ctx, "/artifact/cardano-database/"+url.PathEscape(hash), &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// GetCertificate fetches a certificate by hash for signature verification.
+func (c *Client) GetCertificate(ctx context.Context, hash string) (*Certificate, error) {
+	var out Certificate
+	if err := c.get(ctx, "/certificate/"+url.PathEscape(hash), &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}