Andrew Miller
4dabbcd23a
Add godoc to Create and CreateBulk explaining they return immediately without waiting for block inclusion. Update package-level example to show both fire-and-forget and wait-for-block patterns. Add Transaction Modes section to README with code examples.
156 lines
4.2 KiB
Markdown
Executable File
156 lines
4.2 KiB
Markdown
Executable File
# Dragonchain Go SDK
|
|
|
|
A self-contained Go SDK for interacting with Dragonchain nodes.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get git.dragonchain.com/dragonchain/dragonchain-prime-sdk-go
|
|
```
|
|
|
|
## Usage
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"log"
|
|
"time"
|
|
|
|
"git.dragonchain.com/dragonchain/dragonchain-prime-sdk-go"
|
|
"git.dragonchain.com/dragonchain/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
|
|
- `List(ctx)` - List all transactions
|
|
|
|
### 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
|
|
|
|
## 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") |