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:
51
README.md
51
README.md
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user