Skip to content

TraceBlockTransactions

Gets execution traces for all transactions in a specific block, showing detailed call flow and state changes.

Method Signature

func (provider *Provider) TraceBlockTransactions(ctx context.Context, blockID BlockID) ([]Trace, error)

Parameters

  • ctx - Context for request cancellation and timeout
  • blockID - Block identifier (number, hash, or tag)

Returns

  • []Trace - Array of execution traces for all transactions in the block
  • error - Error if the request fails

Usage Example

package main
 
import (
    "context"
    "encoding/json"
    "fmt"
    "log"
	"os"
 
    "github.com/NethermindEth/starknet.go/rpc"
)
 
func main() {
    // Create RPC client
	// Get RPC URL from environment variable
	rpcURL := os.Getenv("STARKNET_RPC_URL")
	if rpcURL == "" {
		log.Fatal("STARKNET_RPC_URL not set in environment")
	}
 
	ctx := context.Background()
    client, err := rpc.NewProvider(ctx, rpcURL)
    if err != nil {
        log.Fatal("Failed to create client:", err)
    }
 
    // Use a block with known transactions
    blockID := rpc.WithBlockNumber(1676503) // Block that had our transactions
 
    // Trace all transactions in the block
    traces, err := client.TraceBlockTransactions(ctx, blockID)
    if err != nil {
        log.Fatal("Failed to trace block transactions:", err)
    }
 
    // Pretty print the traces (limiting output for readability)
    fmt.Printf("Found %d transaction traces in block\n", len(traces))
    
    if len(traces) > 0 {
        // Show just the first trace structure
        traceJSON, _ := json.MarshalIndent(traces[0], "", "  ")
        fmt.Printf("First transaction trace:\n%s\n", traceJSON)
    }
}

Expected Output

Found 1 transaction traces in block
First transaction trace:
{
  "trace_root": {
    "validate_invocation": {
      "contract_address": "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
      "entry_point_selector": "0x162da33a4585851fe8d3af3c2a9c60b557814e221e0d4f30ff0b2189d9c7775",
      "calldata": [
        "0x1",
        "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
        "0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e",
        "0x3",
        "0x517c64b48079568a30f02967ade11d08f2dfdc45d2c0124650f013d07613802",
        "0x821ab0d4414980000",
        "0x0"
      ],
      "caller_address": "0x0",
      "class_hash": "0x816dd0297efc55dc1e7559020a3a825e81ef734b558f03c83325d4da7e6253",
      "entry_point_type": "EXTERNAL",
      "call_type": "CALL",
      "result": [
        "0x56414c4944"
      ],
      "calls": [],
      "events": [],
      "messages": [],
      "execution_resources": {
        "l1_gas": 0,
        "l2_gas": 480000
      },
      "is_reverted": false
    },
    "execute_invocation": {
      "contract_address": "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
      "entry_point_selector": "0x15d40a3d6ca2ac30f4031e42be28da9b056fef9bb7357ac5e85627ee876e5ad",
      "calldata": [
        "0x1",
        "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
        "0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e",
        "0x3",
        "0x517c64b48079568a30f02967ade11d08f2739d1c4e2677",
        "0x821ab0d4414980000",
        "0x0"
      ],
      "caller_address": "0x0",
      "class_hash": "0x816dd0297efc55dc1e7559020a3a825e81ef734b558f03c83325d4da7e6253",
      "entry_point_type": "EXTERNAL",
      "call_type": "CALL",
      "result": [
        "0x1",
        "0x1",
        "0x1"
      ],
      "calls": [
        {
          "contract_address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "entry_point_selector": "0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e",
          "calldata": [
            "0x517c64b48079568a30f02967ade11d08f2dfdc45d2c0124650f013d07613802",
            "0x821ab0d4414980000",
            "0x0"
          ],
          "caller_address": "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
          "class_hash": "0x9524a94b41c4440a16fd96d7c1ef6ad6f44c1c013e96662734502cd4ee9b1f",
          "entry_point_type": "EXTERNAL",
          "call_type": "CALL",
          "result": [
            "0x1"
          ],
          "calls": [],
          "events": [
            {
              "order": 0,
              "keys": [
                "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
              ],
              "data": [
                "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
                "0x517c64b48079568a30f02967ade11d08f2dfdc45d2c0124650f013d07613802",
                "0x821ab0d4414980000",
                "0x0"
              ]
            }
          ],
          "messages": [],
          "execution_resources": {
            "l1_gas": 0,
            "l2_gas": 190720
          },
          "is_reverted": false
        }
      ],
      "events": [],
      "messages": [],
      "execution_resources": {
        "l1_gas": 0,
        "l2_gas": 390720
      },
      "is_reverted": false
    },
    "fee_transfer_invocation": {
      "contract_address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "entry_point_selector": "0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e",
      "calldata": [
        "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
        "0xee32587f77560",
        "0x0"
      ],
      "caller_address": "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
      "class_hash": "0x9524a94b41c4440a16fd96d7c1ef6ad6f44c1c013e96662734502cd4ee9b1f",
      "entry_point_type": "EXTERNAL",
      "call_type": "CALL",
      "result": [
        "0x1"
      ],
      "calls": [],
      "events": [
        {
          "order": 0,
          "keys": [
            "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
          ],
          "data": [
            "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
            "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
            "0xee32587f77560",
            "0x0"
          ]
        }
      ],
      "messages": [],
      "execution_resources": {
        "l1_gas": 0,
        "l2_gas": 189030
      },
      "is_reverted": false
    },
    "state_diff": {
      "storage_diffs": [
        {
          "address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "storage_entries": [
            {
              "key": "0x1df152ff90ee62c3b2e6371df9bcfdaab763761afbb17039433e3a9ad76c34d",
              "value": "0x7d15a376d0df56159e0"
            },
            {
              "key": "0x470c010d534958f75aa855c0aa22e997a37252dfb7b6a395181dcbb7a9ace02",
              "value": "0x821ab0d4414980000"
            },
            {
              "key": "0x5496768776e3db30053404f18067d81a6e06f5a2b0de326e21298fd9d569a9a",
              "value": "0x22665ce871398fa69a6c2"
            }
          ]
        }
      ],
      "deprecated_declared_classes": [],
      "declared_classes": [],
      "deployed_contracts": [],
      "replaced_classes": [],
      "nonces": [
        {
          "contract_address": "0x324b04e5a4270605007334372ce455c47581e51cdd091559df2739d1c4e2677",
          "nonce": "0x13875"
        }
      ]
    },
    "type": "INVOKE",
    "execution_resources": {
      "l1_gas": 0,
      "l1_data_gas": 224,
      "l2_gas": 1396800
    }
  },
  "transaction_hash": "0x5a8a9b5f9bface71749fb018fcb17931c93d5a284c8a0014f0e999ee0a1d0a4"
}

Error Handling

Common errors include network timeouts and invalid block identifiers. Always check the error before using the returned value.

traces, err := client.TraceBlockTransactions(ctx, blockID)
if err != nil {
    log.Printf("Error tracing block transactions: %v", err)
    return
}
// Safe to use traces

Related Methods