Skip to content

Nonce

Retrieves the nonce (transaction count) for a contract account at a specific block state. The nonce is essential for ensuring transaction ordering and preventing replay attacks. Each transaction from an account must use the current nonce, which increments after each transaction.

Method Signature

func (provider *Provider) Nonce(
    ctx context.Context,
    blockID BlockID,
    contractAddress *felt.Felt,
) (*felt.Felt, error)

Source: contract.go

Parameters

  • ctx (context.Context): Context for request cancellation and timeout
  • blockID (BlockID): Block identifier (number, hash, or tag)
  • contractAddress (*felt.Felt): The address of the contract

Returns

  • *felt.Felt: The contract's nonce at the requested state
  • error: Error if the request fails

Type Definitions

BlockID

The blockID parameter specifies which block state to query. You can identify a block in three ways:

type BlockID struct {
    Number *uint64    `json:"block_number,omitempty"`
    Hash   *felt.Felt `json:"block_hash,omitempty"`
    Tag    BlockTag   `json:"tag,omitempty"`
}

Source: types_block.go

There are helper functions for creating BlockID. So Instead of manually creating the BlockID struct, use these convenience functions.

  • By Block Number - Get a specific block by its height

    blockID := rpc.WithBlockNumber(123456)

    Source: block.go

  • By Block Hash - Get a specific block by its hash

    hash, _ := new(felt.Felt).SetString("0x1234...")
blockID := rpc.WithBlockHash(hash)

    Source: block.go

  • By Block Tag - Get a dynamic block reference

    blockID := rpc.WithBlockTag("latest")      // Latest accepted block
blockID := rpc.WithBlockTag("pending")     // Block currently being built

    Source: block.go

Usage Example

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
 
    "github.com/NethermindEth/starknet.go/rpc"
    "github.com/NethermindEth/starknet.go/utils"
    "github.com/joho/godotenv"
)
 
func main() {
    // Load environment variables from .env file
    err := godotenv.Load()
    if err != nil {
        log.Fatal("Error loading .env file")
    }
 
    // Get RPC URL from environment variable
    rpcURL := os.Getenv("STARKNET_RPC_URL")
    if rpcURL == "" {
        log.Fatal("STARKNET_RPC_URL not found in .env file")
    }
 
    // Initialize provider
    provider, err := rpc.NewProvider(context.Background(), rpcURL)
    if err != nil {
        log.Fatal(err)
    }
 
    ctx := context.Background()
 
    // Example account address
    accountAddress, err := utils.HexToFelt("0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7")
    if err != nil {
        log.Fatal(err)
    }
 
    // Get current nonce
    blockID := rpc.WithBlockTag("latest")
    nonce, err := provider.Nonce(ctx, blockID, accountAddress)
    if err != nil {
        log.Fatal(err)
    }
 
    fmt.Printf("Current nonce: %s\n", nonce)
}

Error Handling

nonce, err := provider.Nonce(ctx, blockID, contractAddress)
if err != nil {
    if errors.Is(err, rpc.ErrContractNotFound) {
        log.Printf("Contract not found at address: %s", contractAddress)
        return
    }
    if errors.Is(err, rpc.ErrBlockNotFound) {
        log.Printf("Block not found")
        return
    }
    log.Printf("Error retrieving nonce: %v", err)
    return
}
 
fmt.Printf("Account nonce: %s\n", nonce)

Common Use Cases

  • Getting the current nonce before sending a transaction to ensure proper ordering.
  • Monitoring account nonces to track transaction activity.
  • Handling pending transactions by checking nonce in both latest and pending blocks.