Document fire-and-forget transaction mode

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.
This commit is contained in:
2026-02-17 13:24:35 -05:00
parent c3d6d017df
commit 4dabbcd23a
3 changed files with 93 additions and 31 deletions

View File

@@ -65,6 +65,57 @@ func main() {
}
```
## 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.