dedupe account/pool queries

Author: dkijania

README.md

@@ -83,7 +83,7 @@ Full API documentation is available on [pkg.go.dev](https://pkg.go.dev/github.co
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `GetSyncStatus()` | `string` | Node sync status (SYNCED, BOOTSTRAP, etc.) |
+| `GetSyncStatus()` | `SyncStatus` | Node sync status (SYNCED, BOOTSTRAP, etc.) |
 | `GetDaemonStatus()` | `*DaemonStatus` | Comprehensive daemon status |
 | `GetNetworkID()` | `string` | Network identifier |
 | `GetAccount(publicKey, tokenID)` | `*AccountData` | Account balance, nonce, delegate |

client.go

@@ -149,14 +149,14 @@ func (c *Client) request(query string, variables map[string]any, queryName strin
 // -- Queries --
 
 // GetSyncStatus returns the node's sync status.
-// Returns one of: CONNECTING, LISTENING, OFFLINE, BOOTSTRAP, SYNCED, CATCHUP.
-func (c *Client) GetSyncStatus() (string, error) {
+// Returns one of the SyncStatus constants (SyncStatusSynced, SyncStatusBootstrap, ...).
+func (c *Client) GetSyncStatus() (SyncStatus, error) {
 	data, err := c.request(querySyncStatus, nil, "get_sync_status")
 	if err != nil {
 		return "", err
 	}
 	var result struct {
-		SyncStatus string `json:"syncStatus"`
+		SyncStatus SyncStatus `json:"syncStatus"`
 	}
 	if err := json.Unmarshal(data, &result); err != nil {
 		return "", err
@@ -172,12 +172,12 @@ func (c *Client) GetDaemonStatus() (*DaemonStatus, error) {
 	}
 	var result struct {
 		DaemonStatus struct {
-			SyncStatus                 string `json:"syncStatus"`
-			BlockchainLength           *int   `json:"blockchainLength"`
-			HighestBlockLengthReceived *int   `json:"highestBlockLengthReceived"`
-			UptimeSecs                 *int   `json:"uptimeSecs"`
-			StateHash                  string `json:"stateHash"`
-			CommitID                   string `json:"commitId"`
+			SyncStatus                 SyncStatus `json:"syncStatus"`
+			BlockchainLength           *int       `json:"blockchainLength"`
+			HighestBlockLengthReceived *int       `json:"highestBlockLengthReceived"`
+			UptimeSecs                 *int       `json:"uptimeSecs"`
+			StateHash                  string     `json:"stateHash"`
+			CommitID                   string     `json:"commitId"`
 			Peers                      []struct {
 				PeerID     string `json:"peerId"`
 				Host       string `json:"host"`
@@ -224,13 +224,15 @@ func (c *Client) GetNetworkID() (string, error) {
 // GetAccount returns account data for a public key.
 // Pass an empty tokenID to use the default MINA token.
 func (c *Client) GetAccount(publicKey, tokenID string) (*AccountData, error) {
-	var data json.RawMessage
-	var err error
+	// tokenID is optional: a non-empty value scopes the query to that token,
+	// while leaving it unset omits the $token variable so the daemon resolves
+	// the default MINA token. A single query serves both cases.
+	vars := map[string]any{"publicKey": publicKey}
 	if tokenID != "" {
-		data, err = c.request(queryGetAccountWithToken, map[string]any{"publicKey": publicKey, "token": tokenID}, "get_account")
-	} else {
-		data, err = c.request(queryGetAccount, map[string]any{"publicKey": publicKey}, "get_account")
+		vars["token"] = tokenID
 	}
+
+	data, err := c.request(queryGetAccount, vars, "get_account")
 	if err != nil {
 		return nil, err
 	}
@@ -290,6 +292,7 @@ func (c *Client) GetAccount(publicKey, tokenID string) (*AccountData, error) {
 // GetBestChain returns blocks from the best chain.
 // Pass 0 for maxLength to use the daemon's default.
 func (c *Client) GetBestChain(maxLength int) ([]BlockInfo, error) {
+	// maxLength <= 0 omits the argument, letting the daemon apply its default.
 	var vars map[string]any
 	if maxLength > 0 {
 		vars = map[string]any{"maxLength": maxLength}
@@ -305,7 +308,7 @@ func (c *Client) GetBestChain(maxLength int) ([]BlockInfo, error) {
 			StateHash               string `json:"stateHash"`
 			CommandTransactionCount int    `json:"commandTransactionCount"`
 			CreatorAccount          struct {
-				PublicKey any `json:"publicKey"`
+				PublicKey string `json:"publicKey"`
 			} `json:"creatorAccount"`
 			ProtocolState struct {
 				ConsensusState struct {
@@ -329,9 +332,11 @@ func (c *Client) GetBestChain(maxLength int) ([]BlockInfo, error) {
 		slotGenesis, _ := strconv.Atoi(b.ProtocolState.ConsensusState.SlotSinceGenesis)
 		slotFork, _ := strconv.Atoi(b.ProtocolState.ConsensusState.Slot)
 
-		creatorPK := "unknown"
-		if v, ok := b.CreatorAccount.PublicKey.(string); ok {
-			creatorPK = v
+		// The daemon may omit the creator public key (e.g. for the genesis
+		// block); fall back to a sentinel so callers get a stable value.
+		creatorPK := b.CreatorAccount.PublicKey
+		if creatorPK == "" {
+			creatorPK = "unknown"
 		}
 
 		blocks[i] = BlockInfo{
@@ -372,13 +377,15 @@ func (c *Client) GetPeers() ([]PeerInfo, error) {
 // GetPooledUserCommands returns pending user commands from the transaction pool.
 // Pass an empty publicKey to get all pending commands.
 func (c *Client) GetPooledUserCommands(publicKey string) ([]PooledUserCommand, error) {
-	var data json.RawMessage
-	var err error
+	// publicKey is optional: a non-empty value filters to that sender, while
+	// leaving it unset omits the $publicKey variable so the daemon returns
+	// every pending command. A single query serves both cases.
+	vars := map[string]any{}
 	if publicKey != "" {
-		data, err = c.request(queryPooledUserCommands, map[string]any{"publicKey": publicKey}, "get_pooled_user_commands")
-	} else {
-		data, err = c.request(queryPooledUserCommandsAll, nil, "get_pooled_user_commands")
+		vars["publicKey"] = publicKey
 	}
+
+	data, err := c.request(queryPooledUserCommands, vars, "get_pooled_user_commands")
 	if err != nil {
 		return nil, err
 	}
@@ -423,6 +430,9 @@ func (c *Client) SendPayment(params SendPaymentParams) (*SendPaymentResult, erro
 		"amount": params.Amount.NanominaString(),
 		"fee":    params.Fee.NanominaString(),
 	}
+
+	// Memo and Nonce are optional: a zero memo and a nil nonce are simply
+	// omitted, letting the daemon assign the next nonce.
 	if params.Memo != "" {
 		input["memo"] = params.Memo
 	}
@@ -508,6 +518,8 @@ func (c *Client) SendDelegation(params SendDelegationParams) (*SendDelegationRes
 // Pass an empty string to disable the SNARK worker.
 // Returns the previous snark worker public key (empty if none).
 func (c *Client) SetSnarkWorker(publicKey string) (string, error) {
+	// A non-empty publicKey sets the SNARK worker; an empty string sends a
+	// null input, which unsets it.
 	var input any
 	if publicKey != "" {
 		input = publicKey

client_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 )
 
 func gqlHandler(data any) http.HandlerFunc {
@@ -39,7 +40,7 @@ func TestGetSyncStatusSynced(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if status != "SYNCED" {
+	if status != SyncStatusSynced {
 		t.Errorf("expected SYNCED, got %s", status)
 	}
 }
@@ -53,7 +54,7 @@ func TestGetSyncStatusBootstrap(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if status != "BOOTSTRAP" {
+	if status != SyncStatusBootstrap {
 		t.Errorf("expected BOOTSTRAP, got %s", status)
 	}
 }
@@ -79,7 +80,7 @@ func TestGetDaemonStatus(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if status.SyncStatus != "SYNCED" {
+	if status.SyncStatus != SyncStatusSynced {
 		t.Errorf("expected SYNCED, got %s", status.SyncStatus)
 	}
 	if status.BlockchainLength == nil || *status.BlockchainLength != 100 {
@@ -315,7 +316,7 @@ func TestConnectionErrorAfterRetries(t *testing.T) {
 		WithGraphQLURI("http://127.0.0.1:1/graphql"),
 		WithRetries(2),
 		WithRetryDelay(0),
-		WithTimeout(100*1000*1000), // 100ms in nanoseconds... use time.Duration
+		WithTimeout(100*time.Millisecond),
 	)
 	defer client.Close()
 

currency.go

@@ -71,6 +71,8 @@ func (c Currency) Nanomina() uint64 {
 }
 
 // Mina returns the decimal string representation in whole MINA (e.g. "1.500000000").
+// The fractional part is always rendered with the full 9 nanomina digits so the
+// output round-trips exactly through CurrencyFromString.
 func (c Currency) Mina() string {
 	s := strconv.FormatUint(c.nanomina, 10)
 	if len(s) > 9 {
@@ -150,6 +152,10 @@ func (e *CurrencyUnderflowError) Error() string {
 	return fmt.Sprintf("subtraction would result in negative: %s - %s", e.A, e.B)
 }
 
+// parseDecimal converts a decimal MINA string (e.g. "1.5") into nanomina.
+// It is implemented by hand rather than via a float/decimal library to keep
+// the package dependency-free and to avoid binary-floating-point rounding of
+// nanomina amounts.
 func parseDecimal(s string) (uint64, error) {
 	segments := strings.SplitN(s, ".", 3)
 	switch len(segments) {

examples/basic_usage.go

@@ -6,6 +6,7 @@ package main
 import (
 	"fmt"
 	"log"
+	"time"
 
 	mina "github.com/MinaProtocol/mina-sdk-go"
 )
@@ -73,8 +74,8 @@ func connectToRemoteNode() {
 	client := mina.NewClient(
 		mina.WithGraphQLURI("http://my-mina-node:3085/graphql"),
 		mina.WithRetries(5),
-		mina.WithRetryDelay(10_000_000_000), // 10 seconds
-		mina.WithTimeout(60_000_000_000),    // 60 seconds
+		mina.WithRetryDelay(10*time.Second),
+		mina.WithTimeout(60*time.Second),
 	)
 	defer client.Close()
 

integration_test.go

@@ -81,9 +81,9 @@ func TestIntegrationSyncStatus(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	validStatuses := map[string]bool{
-		"CONNECTING": true, "LISTENING": true, "OFFLINE": true,
-		"BOOTSTRAP": true, "SYNCED": true, "CATCHUP": true,
+	validStatuses := map[mina.SyncStatus]bool{
+		mina.SyncStatusConnecting: true, mina.SyncStatusListening: true, mina.SyncStatusOffline: true,
+		mina.SyncStatusBootstrap: true, mina.SyncStatusSynced: true, mina.SyncStatusCatchup: true,
 	}
 	if !validStatuses[status] {
 		t.Errorf("unexpected sync status: %s", status)

queries.go

@@ -32,24 +32,11 @@ query {
 }
 `
 
+// queryGetAccount fetches a single account. The token argument is optional:
+// $token is a nullable TokenId, and when no token variable is supplied the
+// daemon resolves the default MINA token.
 const queryGetAccount = `
-query ($publicKey: PublicKey!) {
-    account(publicKey: $publicKey) {
-        publicKey
-        nonce
-        delegate
-        tokenId
-        balance {
-            total
-            liquid
-            locked
-        }
-    }
-}
-`
-
-const queryGetAccountWithToken = `
-query ($publicKey: PublicKey!, $token: TokenId!) {
+query ($publicKey: PublicKey!, $token: TokenId) {
     account(publicKey: $publicKey, token: $token) {
         publicKey
         nonce
@@ -93,8 +80,11 @@ query {
 }
 `
 
+// queryPooledUserCommands lists pending user commands. The publicKey argument
+// is optional: $publicKey is a nullable PublicKey, and when no variable is
+// supplied the daemon returns commands for every sender.
 const queryPooledUserCommands = `
-query ($publicKey: PublicKey!) {
+query ($publicKey: PublicKey) {
     pooledUserCommands(publicKey: $publicKey) {
         id
         hash
@@ -108,21 +98,6 @@ query ($publicKey: PublicKey!) {
 }
 `
 
-const queryPooledUserCommandsAll = `
-query {
-    pooledUserCommands {
-        id
-        hash
-        kind
-        nonce
-        amount
-        fee
-        from
-        to
-    }
-}
-`
-
 const mutationSendPayment = `
 mutation ($input: SendPaymentInput!) {
     sendPayment(input: $input) {

scripts/check_schema_drift.go

@@ -18,6 +18,11 @@
 //	go run scripts/check_schema_drift.go --endpoint http://127.0.0.1:8080/graphql --branch master --strict
 package main
 
+// The schema diff is implemented in-package (rather than via a JSON-diff
+// dependency) so this `go:build ignore` tool stays dependency-free and the
+// output can be tuned to GraphQL-specific drift categories. Output is
+// human-readable by design; if a machine-readable format is needed later,
+// emit JSON behind a flag.
 import (
 	"bytes"
 	"encoding/json"

types.go

@@ -2,6 +2,20 @@ package mina
 
 import "encoding/json"
 
+// SyncStatus is a Mina node's synchronization status, as reported by the
+// daemon's syncStatus / daemonStatus.syncStatus fields.
+type SyncStatus string
+
+// Known sync statuses returned by the Mina daemon.
+const (
+	SyncStatusConnecting SyncStatus = "CONNECTING"
+	SyncStatusListening  SyncStatus = "LISTENING"
+	SyncStatusOffline    SyncStatus = "OFFLINE"
+	SyncStatusBootstrap  SyncStatus = "BOOTSTRAP"
+	SyncStatusSynced     SyncStatus = "SYNCED"
+	SyncStatusCatchup    SyncStatus = "CATCHUP"
+)
+
 // AccountBalance represents the balance of a Mina account.
 type AccountBalance struct {
 	Total  Currency
@@ -27,7 +41,7 @@ type PeerInfo struct {
 
 // DaemonStatus represents the status of the Mina daemon.
 type DaemonStatus struct {
-	SyncStatus                 string
+	SyncStatus                 SyncStatus
 	BlockchainLength           *int
 	HighestBlockLengthReceived *int
 	UptimeSecs                 *int