cursor.go

Overview

The [cursor.go](/projects/291/69107) file defines a data structure and related functionality to manage cursor-based pagination state within the Cosmos blockchain context. It provides mechanisms to serialize and deserialize a cursor object that tracks pagination progress across multiple paginated queries, especially when querying blockchain transactions and blocks.

This cursor enables clients to resume paginated queries efficiently without losing context, by storing information such as block height, transaction index, and transaction-specific pagination state. The cursor is encoded as a base64 string for safe transmission and storage, and decoded back into the structured format when needed.

Detailed Documentation

Types

CursorState

type CursorState struct {
    TxID string `json:"txid"`
    Page int    `json:"page"`
}

• Purpose: Holds pagination state specific to a single transaction identified by its transaction ID (TxID).

• Fields:

  • TxID (string): The transaction ID associated with this pagination state.

  • Page (int): The current page number within the transaction pagination.

Cursor

type Cursor struct {
    BlockHeight int64                    `json:"blockHeight"`
    TxIndex     *int                    `json:"txIndex"`
    State       map[string]*CursorState `json:"state"`
}

• Purpose: Represents the overall cursor state for paginated blockchain queries.

• Fields:

  • BlockHeight (int64): The height of the blockchain block where the cursor currently points.

  • TxIndex (*int): A pointer to an integer indicating the index of the transaction within the block. It is a pointer to allow nil value meaning no current transaction.

  • State (map[string]*CursorState): A map where keys are string identifiers (likely transaction hashes or similar) and values are pointers to CursorState. This stores per-transaction pagination states.

Methods

encode() (string, error)

func (c *Cursor) encode() (string, error)

• Purpose: Serializes the Cursor instance into a JSON string, then encodes this string into base64 format for safe transmission or storage.

• Returns:

  • string: The base64 encoded representation of the cursor.

  • error: Returns an error if JSON marshaling fails.

• Implementation Details:

  1. Marshal the Cursor struct to JSON bytes.

  2. Base64 encode the JSON string.

  3. Return the base64 string or error if marshaling fails.

• Usage Example:

cursor := &Cursor{
    BlockHeight: 123456,
    TxIndex:     ptrInt(2),
    State: map[string]*CursorState{
        "txhash1": {TxID: "txhash1", Page: 1},
    },
}

encoded, err := cursor.encode()
if err != nil {
    log.Fatal(err)
}
fmt.Println("Encoded Cursor:", encoded)

decode(b64 string) error

func (c *Cursor) decode(b64 string) error

• Purpose: Decodes a base64 encoded string into JSON, then unmarshals it to populate the Cursor object.

• Parameters:

  • b64 (string): The base64 encoded cursor string.

• Returns:

  • error: Returns an error if base64 decoding or JSON unmarshaling fails.

• Implementation Details:

  1. Decode the base64 string into JSON bytes.

  2. Unmarshal the JSON bytes into the Cursor struct.

  3. Return any errors encountered.

• Usage Example:

var cursor Cursor
err := cursor.decode(encodedString)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Decoded Cursor: %+v\n", cursor)

Important Implementation Details

• Pointer Usage for TxIndex:
  The TxIndex is declared as a pointer to int (*int) instead of a plain int. This allows the cursor to differentiate between an unset transaction index (nil) and zero, which can be important for correctly resuming pagination.

• Error Wrapping:
  The methods use github.com/pkg/errors to wrap errors with descriptive messages, including context such as the cursor content or base64 string. This enhances debugging and traceability.

• Base64 Encoding:
  Base64 encoding ensures the cursor string can be safely transported over protocols that may not be binary safe or that require URL-safe transmission.

Interaction with Other Parts of the System

• Pagination Workflow:
  This file is part of the pagination mechanism within the system that queries Cosmos blockchain data. The cursor tracks the current position in the blockchain (by block height and transaction index) and tracks progress inside individual transactions.

• State Persistence:
  The encoded cursor string is likely stored or sent between client and server to maintain state across paginated API calls or queries.

• Integration Points:
  Other components responsible for querying blockchain transactions or blocks will instantiate and update this cursor to manage pagination state.

Visual Diagram

classDiagram
    class Cursor {
        +int64 BlockHeight
        +*int TxIndex
        +map[string]*CursorState State
        +encode() string, error
        +decode(b64 string) error
    }
    class CursorState {
        +string TxID
        +int Page
    }
    Cursor --> "1..*" CursorState : contains

Summary

The [cursor.go](/projects/291/69107) file provides a robust, easy-to-use cursor abstraction to support pagination over Cosmos blockchain data. It encapsulates the pagination state in a structured format and provides encoding/decoding utilities to facilitate persistence and transmission. This enables efficient, reliable paginated queries that can be resumed seamlessly, improving performance and user experience in blockchain data retrieval workflows.