Stellar PHP SDK API Documentation

TOID
in package

SEP-35 operation ID (also known as Horizon's "TOID": total order ID).

SEP-35 defines the ID scheme used for Stellar operations in historical ledger data. An ID is a single signed 64-bit integer that packs three big-endian bit fields: a 32-bit ledger sequence, a 20-bit transaction application order, and a 12-bit operation index, encoded as id = (ledgerSequence << 32) | (transactionOrder << 12) | operationIndex. The sign bit of the encoded value is never set for valid field values, which keeps IDs usable directly as SQL bigint primary keys and cursors.

IDs are represented with PHP's native int type, which requires a 64-bit PHP build; this SDK assumes a 64-bit build throughout.

On the network, transaction application order and operation index are assigned starting at 1. Nonetheless, this class accepts 0 for both fields, since 0 is a valid encoded value and is required to express range boundaries such as new TOID($ledgerSequence, 0, 0). Ledger sequence 0 is accepted for the same reason by the constructor and by TOID::afterLedger(). TOID::ledgerRangeInclusive() is stricter: it requires $from >= 1, because the network's first ledger is 1 and a smaller range start is a caller error rather than a valid boundary. Separately, that method special-cases $from === 1 by pulling the computed range start down to 0, so that IDs encoded with ledger field 0 still fall inside the lowest range.

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md
TOIDRange

Table of Contents

Constants

MAX_LEDGER_SEQUENCE  : mixed = 2147483647
Largest ledger sequence encodable in the 32-bit ledger sequence field.
MAX_OPERATION_INDEX  : mixed = 4095
Largest operation index encodable in the 12-bit field.
MAX_TRANSACTION_ORDER  : mixed = 1048575
Largest transaction application order encodable in the 20-bit field.

Methods

__construct()  : mixed
afterLedger()  : TOID
Returns the largest encodable ID within the given ledger.
fromInt64()  : TOID
Decodes a signed 64-bit encoded ID into its three fields.
getLedgerSequence()  : int
Returns the ledger sequence field.
getOperationIndex()  : int
Returns the operation index field.
getTransactionOrder()  : int
Returns the transaction application order field.
incrementOperationIndex()  : void
Advances this ID to the next operation slot, for use as a cursor while iterating.
ledgerRangeInclusive()  : TOIDRange
Returns the range of encoded IDs covering ledgers $from through $to, inclusive.
toInt64()  : int
Encodes the three fields into a single signed 64-bit integer, as defined by SEP-35.

Constants

MAX_LEDGER_SEQUENCE

Largest ledger sequence encodable in the 32-bit ledger sequence field.

public mixed MAX_LEDGER_SEQUENCE = 2147483647

MAX_OPERATION_INDEX

Largest operation index encodable in the 12-bit field.

public mixed MAX_OPERATION_INDEX = 4095

MAX_TRANSACTION_ORDER

Largest transaction application order encodable in the 20-bit field.

public mixed MAX_TRANSACTION_ORDER = 1048575

Methods

__construct()

public __construct(int $ledgerSequence, int $transactionOrder, int $operationIndex) : mixed
Parameters
$ledgerSequence : int

the ledger the operation was validated in, between 0 and 2147483647

$transactionOrder : int

the application order of the transaction within the ledger, between 0 and 1048575

$operationIndex : int

the index of the operation within the transaction, between 0 and 4095

Tags
throws
InvalidArgumentException

if any field is outside of its valid encoding range

afterLedger()

Returns the largest encodable ID within the given ledger.

public static afterLedger(int $ledgerSequence) : TOID

This is useful as an inclusive upper query bound: compare candidate IDs with <= against the result. This is the opposite convention from TOID::ledgerRangeInclusive(), whose end value is exclusive and must be compared with <.

Parameters
$ledgerSequence : int

the ledger sequence, between 0 and 2147483647

Tags
throws
InvalidArgumentException

if $ledgerSequence is outside of its valid range

Return values
TOID —

the ID ($ledgerSequence, 1048575, 4095)

fromInt64()

Decodes a signed 64-bit encoded ID into its three fields.

public static fromInt64(int $value) : TOID

The ledger sequence is the top 32 bits, $value >> 32; the transaction order is the next 20 bits, ($value >> 12) & 0xFFFFF; and the operation index is the bottom 12 bits, $value & 0xFFF. PHP's native int cannot exceed 2^63 - 1, so there is no separate upper bound check: any non-negative int decodes into field values that already satisfy the constructor's valid ranges.

Parameters
$value : int

the encoded ID to decode

Tags
throws
InvalidArgumentException

if $value is negative. A negative value has its sign bit set, which is never valid for an encoded ID, and right-shifting it would otherwise produce a ledger sequence outside of the encoding domain.

Return values
TOID —

the decoded ID

getLedgerSequence()

Returns the ledger sequence field.

public getLedgerSequence() : int
Return values
int —

the ledger the operation was validated in, between 0 and 2147483647

getOperationIndex()

Returns the operation index field.

public getOperationIndex() : int
Return values
int —

the index of the operation within the transaction, between 0 and 4095

getTransactionOrder()

Returns the transaction application order field.

public getTransactionOrder() : int
Return values
int —

the order of the transaction within the ledger, between 0 and 1048575

incrementOperationIndex()

Advances this ID to the next operation slot, for use as a cursor while iterating.

public incrementOperationIndex() : void

The operation index is incremented. When it is already at its maximum value of 4095, it is reset to 0 and the ledger sequence is incremented instead; the transaction application order is left unchanged in both cases, since the next operation slot after the last operation index of a transaction is not known to belong to any particular later transaction.

Tags
throws
OverflowException

if the operation index is already 4095 and the ledger sequence is already 2147483647. Incrementing further would require a state that the constructor would reject, and encoding it would set the sign bit.

ledgerRangeInclusive()

Returns the range of encoded IDs covering ledgers $from through $to, inclusive.

public static ledgerRangeInclusive(int $from, int $to) : TOIDRange

The range start is (new TOID($from, 0, 0))->toInt64(), except when $from is 1, in which case the start is 0 instead, so that the range also covers any ID encoded with ledger field 0. The range end is (new TOID($to + 1, 0, 0))->toInt64() and is exclusive: callers must compare candidate IDs with < against it, not <=.

Parameters
$from : int

the first ledger sequence to include, at least 1

$to : int

the last ledger sequence to include

Tags
throws
InvalidArgumentException

if $from is greater than $to, if $from is less than 1, or if $to is not strictly less than 2147483647 (the range end is computed from $to + 1, which must still fit within the ledger sequence field)

Return values
TOIDRange —

the ID range covering ledgers $from through $to

toInt64()

Encodes the three fields into a single signed 64-bit integer, as defined by SEP-35.

public toInt64() : int
Return values
int —

the encoded ID: (ledgerSequence << 32) | (transactionOrder << 12) | operationIndex

On this page

Search results