prime-sdk-go/README.md

# Dragonchain Go SDK

A self-contained Go SDK for interacting with Dragonchain nodes.

## Installation

```bash
go get git.dragonchain.com/dragonchain/prime-sdk-go
```

## Usage

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "git.dragonchain.com/dragonchain/prime-sdk-go"
    "git.dragonchain.com/dragonchain/prime-sdk-go/models"
)

func main() {
    // Initialize the SDK
    client := sdk.NewDragonchainSDK(
        "your-public-id",
        "your-auth-key-id",
        "your-auth-key",
        "https://your-dragonchain-endpoint.com",
    )

    // Create a context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Check system health
    if err := client.System.Health(ctx); err != nil {
        log.Fatal("Health check failed:", err)
    }

    // Get system status
    status, err := client.System.Status(ctx)
    if err != nil {
        log.Fatal("Failed to get status:", err)
    }
    fmt.Printf("Chain ID: %s, Level: %d\n", status.ID, status.Level)

    // Create a transaction
    txn := &models.TransactionCreateRequest{
        TxnType: "my-transaction-type",
        Payload: map[string]interface{}{
            "message": "Hello Dragonchain",
        },
        Tag: "example-tag",
    }

    resp, err := client.Transaction.Create(ctx, txn)
    if err != nil {
        log.Fatal("Failed to create transaction:", err)
    }
    fmt.Printf("Created transaction: %s\n", resp.TransactionID)
}
```

## Transaction Modes

`Create` and `CreateBulk` return **immediately** with the assigned transaction ID(s). They do **not** wait for block inclusion. Blocks are assembled asynchronously on a ~5-second cycle.

### Fire and Forget

Most use cases only need the transaction ID. No polling required.

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

resp, err := client.Transaction.Create(ctx, &models.TransactionCreateRequest{
    TxnType: "my-transaction-type",
    Payload: `{"message": "Hello Dragonchain"}`,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Transaction ID: %s\n", resp.TransactionID)
// Done — no need to wait for a block.
```

### Wait for Block

If you need the block ID (e.g. for interchain verification or Daria), poll `Get` until `Header.BlockId` is populated.

```go
resp, err := client.Transaction.Create(ctx, &models.TransactionCreateRequest{
    TxnType: "my-transaction-type",
    Payload: `{"message": "Hello Dragonchain"}`,
})
if err != nil {
    log.Fatal(err)
}

// Poll until the transaction is included in a block.
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for range ticker.C {
    txn, err := client.Transaction.Get(ctx, resp.TransactionID)
    if err != nil {
        log.Fatal(err)
    }
    if txn.Header.BlockId != "" {
        fmt.Printf("Block ID: %s\n", txn.Header.BlockId)
        break
    }
}
```

## Available Endpoints

All API methods accept a `context.Context` as their first parameter for timeout and cancellation control.

### System
- `Health(ctx)` - Check system health
- `Status(ctx)` - Get system status

### Transaction
- `Create(ctx, req)` - Create a new transaction
- `CreateBulk(ctx, req)` - Create multiple transactions
- `Get(ctx, transactionID)` - Get transaction by ID
- `GetInterchain(ctx, transactionID, opts...)` - Trace a transaction's interchain anchors
- `List(ctx)` - List all transactions

#### Interchain trace options

`Transaction.GetInterchain` and `Block.GetInterchain` trace a prime block to the
public-chain anchors covering it. By default they return the **first anchor per
chain** (anchor proofs are chained, so the earliest per chain is the meaningful
one). Tune with functional options:

```go
// Default: first anchor per chain (ETH, BTC, …)
trace, _ := client.Block.GetInterchain(ctx, "42")

// Up to 3 anchors per chain
trace, _ = client.Block.GetInterchain(ctx, "42", sdk.WithPerChain(3))

// All anchors, only the ETH-mainnet chain ("1"); "0" = BTC
trace, _ = client.Block.GetInterchain(ctx, "42", sdk.WithPerChain(0), sdk.WithChains("1"))
```

### Transaction Type
- `Create(ctx, req)` - Create a new transaction type
- `Get(ctx, txnType)` - Get transaction type by name
- `List(ctx)` - List all transaction types
- `Delete(ctx, txnType)` - Delete a transaction type

### Smart Contract
- `Create(ctx, req)` - Create a new smart contract
- `Get(ctx, contractID)` - Get smart contract by ID
- `List(ctx)` - List all smart contracts
- `Update(ctx, contractID, req)` - Update a smart contract
- `Upload(ctx, contractID, filepath)` - Upload smart contract code
- `Delete(ctx, contractID)` - Delete a smart contract

### Block
- `Get(ctx, blockID)` - Get block by ID

### Proof Measure (public, unauthenticated)
- `GetSecurity(ctx, network, since)` - A network's accumulated security since `since` (unix seconds; `0` = service default), as raw measure + USD valuation. `network` = `"BTC"` or `"ETH"`.
- `Report(ctx, req)` - Per-transaction "securedBy" report over interchain anchors.
- `Health(ctx)` - Service liveness.

## Proof Measure

`proof-measure` is a separate, **public, unauthenticated** Dragonchain service
(the measured-immutability / "securedBy" metric) at
`https://proof-measure.dragonchain.com`. It needs no credentials. The SDK exposes
it two ways:

```go
// 1. Via the main SDK (targets the default public endpoint):
sec, err := client.ProofMeasure.GetSecurity(ctx, "BTC", time.Now().Add(-time.Hour).Unix())
if err != nil {
    log.Fatal(err)
}
fmt.Printf("BTC secured by %s (%s) since %d\n", sec.ValueUSDFormatted, sec.Raw.Value+" "+sec.Raw.Unit, sec.SinceUnix)

// 2. Standalone (no prime credentials needed; empty URL = public prod):
import "git.dragonchain.com/dragonchain/prime-sdk-go/proofmeasure"

pm := proofmeasure.NewProofMeasureClient("") // or a custom base URL
report, err := pm.Report(ctx, &models.ReportRequest{
    TransactionID: "tx-123", PrimeID: "my-prime", BlockID: "42",
    Anchors: []models.ReportAnchorInput{
        {Network: "BTC", TxHash: "0x...", Timestamp: anchorUnix},
        {Network: "ETH", TxHash: "0x...", Timestamp: anchorUnix},
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Secured by %s across %d anchors\n", report.TotalValueUSDFormatted, len(report.Anchors))
```

## Authentication

The SDK uses HMAC-SHA256 authentication. You need to provide:
- `publicID` - Your Dragonchain public ID
- `authKeyID` - Your authentication key ID
- `authKey` - Your authentication key
- `baseURL` - The base URL of your Dragonchain node (e.g., "https://chains.dragonchain.com")