Go SDK¶

The PrimeStamp Go SDK provides a native Go client for the PrimeStamp timestamping API. It supports SHA3-256 and SHA-256 hashing, functional options for configuration, and full stamp lifecycle management.

Installation¶

go get github.com/brianmolidor/primestamp-go

Quick Start¶

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/brianmolidor/primestamp-go/primestamp"
)

func main() {
    client := primestamp.NewClient("https://api.primestamp.io", "your-api-key")

    ctx := context.Background()

    // Stamp content
    stamp, err := client.StampContent(ctx, []byte("Hello, World!"))
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Stamp ID: %s\n", stamp.ID)

    // Verify content
    result, err := client.Verify(ctx, stamp.ID, []byte("Hello, World!"))
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Verified: %v\n", result.Verified)
}

Client Configuration¶

Use functional options to configure the client.

import (
    "net/http"
    "time"
)

client := primestamp.NewClient(
    "https://api.primestamp.io",
    "your-api-key",
    primestamp.WithTimeout(60 * time.Second),
    primestamp.WithHashAlgorithm(primestamp.SHA256),
    primestamp.WithHTTPClient(&http.Client{
        Transport: &http.Transport{
            MaxIdleConns: 10,
        },
    }),
)

Option	Description
`WithHTTPClient(client)`	Use a custom `*http.Client`.
`WithHashAlgorithm(algo)`	Set default hash algorithm (`SHA3256` or `SHA256`).
`WithTimeout(duration)`	Set HTTP client timeout. Default: 30s.

Hash Algorithms¶

Constant	Value	Description
`primestamp.SHA3256`	`"sha3-256"`	Default. Most secure.
`primestamp.SHA256`	`"sha256"`	Widely compatible.

hash := primestamp.ComputeHash([]byte("content"), primestamp.SHA3256)
// "sha3-256:a1b2c3..."

Stamping¶

Stamp Raw Content¶

stamp, err := client.StampContent(ctx, content,
    primestamp.WithMetadata("author", "alice"),
    primestamp.WithDescription("Quarterly report"),
)

Stamp a Pre-Computed Hash¶

stamp, err := client.StampHash(ctx, "sha3-256:abc123...")

Stamp a File¶

file, _ := os.Open("report.pdf")
defer file.Close()

stamp, err := client.StampFile(ctx, file,
    primestamp.WithMetadata("filename", "report.pdf"),
)

Verification¶

result, err := client.Verify(ctx, stamp.ID, content)
fmt.Printf("Verified: %v\n", result.Verified)
fmt.Printf("Timestamp: %s\n", result.Timestamp)

// Verify a pre-computed hash
result, err := client.VerifyHash(ctx, stampID, "sha3-256:abc123...")

Listing and Retrieving Stamps¶

// List stamps with filters
stamps, err := client.ListStamps(ctx, &primestamp.ListOptions{
    Limit:  20,
    Offset: 0,
    After:  time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC),
})

for _, s := range stamps {
    fmt.Printf("%s: %s\n", s.ID, s.ContentHash)
}

// Get a single stamp
stamp, err := client.GetStamp(ctx, "stamp-id-here")

Data Types¶

Stamp¶

type Stamp struct {
    ID          string            `json:"id"`
    ContentHash string            `json:"contentHash"`
    Algorithm   string            `json:"algorithm"`
    Timestamp   time.Time         `json:"timestamp"`
    Proof       *Proof            `json:"proof,omitempty"`
    Metadata    map[string]string `json:"metadata,omitempty"`
}

VerificationResult¶

type VerificationResult struct {
    Verified    bool      `json:"verified"`
    StampID     string    `json:"stampId"`
    ContentHash string    `json:"contentHash"`
    Timestamp   time.Time `json:"timestamp"`
    Message     string    `json:"message,omitempty"`
}

Error Handling¶

stamp, err := client.GetStamp(ctx, "nonexistent")
if err == primestamp.ErrStampNotFound {
    fmt.Println("Stamp does not exist")
} else if err != nil {
    fmt.Printf("API error: %v\n", err)
}

Context Support

All client methods accept a context.Context as the first argument, supporting cancellation and deadlines.

Concurrency

The client is safe for concurrent use across goroutines. The underlying http.Client manages its own connection pool.