MonitorTransactionState

Monitor Transaction state changes by the unique identifier of the transaction. Server-side streaming method that sends state updates as the transaction progresses.

Server-Side Streaming Method

This method uses server-side streaming, meaning it returns multiple responses over time rather than a single response. The server sends a stream of responses to the client, and the client processes each response as it arrives.

Stream Lifecycle:

• Initiation: Call the method to create a stream
• Data Reception: Receive multiple responses over the stream
• Completion: Stream ends normally (EOF/end event) or with an error
• Resource Management: Streams should be fully consumed or explicitly closed

See the code examples below for language-specific streaming consumption patterns.

Overview

Method Options

Authorisation specification of the MonitorTransactionState method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_LEDGER_ADMIN ROLE_LEDGER_VIEWER ROLE_LEDGER_TRANSACTION_ADMIN ROLE_LEDGER_TRANSACTION_VIEWER

Parameters

Request and response parameter message overview:

Input: MonitorTransactionStateRequest Message

Field	Type	Required	Description
Name	string	True	Name of the Transaction whose state is to be retrieved. Format: transactions/{ULIDv2}

Returns: MonitorTransactionStateResponse Message

Field	Type	Description
State	meshtrade.ledger.transaction.v1.TransactionState

Protobuf

syntax = "proto3";

package meshtrade.ledger.transaction.v1;

import "buf/validate/validate.proto";
import "meshtrade/ledger/transaction/v1/transaction_state.proto";
import "meshtrade/option/method_options/v1/method_options.proto";

option go_package = "github.com/meshtrade/api/go/ledger/transaction/v1;transaction_v1";
option java_package = "co.meshtrade.api.ledger.transaction.v1";

/*
   TransactionService manages Transaction lifecycle.
*/
service TransactionService {
  /*
     Retrieves a single Transaction state by the unique identifier of the transaction
  */
  rpc GetTransactionState(GetTransactionStateRequest) returns (GetTransactionStateResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_LEDGER_ADMIN,
        ROLE_LEDGER_VIEWER,
        ROLE_LEDGER_TRANSACTION_ADMIN,
        ROLE_LEDGER_TRANSACTION_VIEWER
      ]
    };
  }

  /*
     Monitor Transaction state changes by the unique identifier of the transaction.
     Server-side streaming method that sends state updates as the transaction progresses.
  */
  rpc MonitorTransactionState(MonitorTransactionStateRequest) returns (stream MonitorTransactionStateResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_LEDGER_ADMIN,
        ROLE_LEDGER_VIEWER,
        ROLE_LEDGER_TRANSACTION_ADMIN,
        ROLE_LEDGER_TRANSACTION_VIEWER
      ]
    };
  }
}

message GetTransactionStateRequest {
  /*
     Name of the Transaction whose state is to be retrieved.
     Format: transactions/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 39
      pattern: "^transactions/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

message GetTransactionStateResponse {
  meshtrade.ledger.transaction.v1.TransactionState state = 1;
}

message MonitorTransactionStateRequest {
  /*
     Name of the Transaction whose state is to be retrieved.
     Format: transactions/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 39
      pattern: "^transactions/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

message MonitorTransactionStateResponse {
  meshtrade.ledger.transaction.v1.TransactionState state = 1;
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"io"
	"log"

	transactionv1 "github.com/meshtrade/api/go/ledger/transaction/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := transactionv1.NewTransactionService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with service-specific parameters
	request := &transactionv1.MonitorTransactionStateRequest{
		// FIXME: Populate service-specific request fields
	}

	// Call the MonitorTransactionState streaming method
	stream, err := service.MonitorTransactionState(ctx, request)
	if err != nil {
		log.Fatalf("Failed to initiate stream: %v", err)
	}

	// Consume stream responses
	for {
		response, err := stream.Recv()
		if err == io.EOF {
			break // Stream completed normally
		}
		if err != nil {
			log.Fatalf("Stream error: %v", err)
		}

		// Process each response as it arrives
		log.Printf("Received: %+v", response)
	}

	log.Println("Stream completed successfully")
}

Python

from meshtrade.ledger.transaction.v1 import (
    MonitorTransactionStateRequest,
    TransactionService,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = TransactionService()

    with service:
        # Create request with service-specific parameters
        request = MonitorTransactionStateRequest(
            # FIXME: Populate service-specific request fields
        )

        # Call the MonitorTransactionState streaming method
        stream = service.monitor_transaction_state(request)

        try:
            # Consume stream responses using iterator pattern
            for response in stream:
                # Process each response as it arrives
                print("Received:", response)

            print("Stream completed successfully")
        except Exception as e:
            print("Stream error:", e)
            raise


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.ledger.transaction.v1.TransactionService;
import co.meshtrade.api.ledger.transaction.v1.Service.MonitorTransactionStateRequest;
import co.meshtrade.api.ledger.transaction.v1.Service.MonitorTransactionStateResponse;

import java.util.Iterator;
import java.util.Optional;

public class MonitorTransactionStateExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (TransactionService service = new TransactionService()) {
            // Create request with service-specific parameters
            MonitorTransactionStateRequest request = MonitorTransactionStateRequest.newBuilder()
                // FIXME: Populate service-specific request fields
                .build();

            // Call the MonitorTransactionState streaming method
            Iterator<MonitorTransactionStateResponse> stream = service.monitorTransactionState(request, Optional.empty());

            // Consume stream responses using iterator pattern
            while (stream.hasNext()) {
                MonitorTransactionStateResponse response = stream.next();

                // Process each response as it arrives
                System.out.println("Received: " + response);
            }

            System.out.println("Stream completed successfully");
        } catch (Exception e) {
            System.err.println("MonitorTransactionState stream failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Ledger Transaction v1 Method List - For Other methods