1 of 6

Serialization

sto_subfield

Index into a xahaud serialized object and return the location and length of a subfield

Concepts

Serialized Objects

Behaviour

Parse a STObject pointed to by read_ptr
Find the field specified by field_id
If the field is found, and:
1. It is an array, then return the start and length of the array including the leadin/leadout bytes, or
1. It is not an array, then return the start and length of the PAYLOAD of the field (excluding the leadin bytes).

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_subfield (
    uint32_t read_ptr,
  	uint32_t read_len,
  	uint32_t field_id
);

Example

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
int64_t memo_lookup =
    sto_subfield(memo_ptr, memo_len, sfMemo);
if (memo_lookup < 0)
{
    // sfMemo was not found in the STObject pointed at by memo_ptr
}
else
{
    // sfMemo was found and its location is as follows:
	  uint8_t* memo_ptr = SUB_OFFSET(memo_lookup) + memo_ptr;
	  int64_t  memo_len = SUB_LENGTH(memo_lookup);
}

📘
hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the STObject

read_len

uint32_t

Length of STObject

field_id

uint32_t

The sf code of the field you are searching for. To compute this manually take the serialized type and shift it into the 16 highest bits of uint32_t, then take the field and place it in the 16 lowest bits. For example: sfEmitNonce has type 5 and field 11 thus its value is 0x050BU

Return Code

Type

Description

int64_t

The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Input buffer isn't large enough to possibly contain a valid STObject. DOESNT_EXIST - The searched for field isn't present in the supplied STObject. PARSE_ERROR - The supplied STObject is malformed or not an STObject.

sto_subarray

Index into a xahaud serialized array and return the location and length of an index

Concepts

Serialized Objects

Behaviour

Parse a STArray pointed to by read_ptr
Find the array index specified by array_id
Return the byte offset and length of the serialized field within the STObject, if it is found

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.
In the case of this array field ID is array_id.

Definition

int64_t sto_subfield (
    uint32_t read_ptr,
  	uint32_t read_len,
  	uint32_t array_id
);

Example

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))

  int64_t memo_lookup =
    sto_subarray(memos, memos_len, 0);

if (memo_lookup < 0)
{
    // sfMemo was not found in the STObject pointed at by memo_ptr
}
else
{
    // 0th index of the STArray was found and its location is as follows:
    uint8_t*  memo_ptr = SUB_OFFSET(memo_lookup) + memos;
    uint32_t  memo_len = SUB_LENGTH(memo_lookup);
}

📘
hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the STArray

read_len

uint32_t

Length of STArray

array_id

uint32_t

The index of the entry within the STArray you are seeking. Starts from 0.

Return Code

Type

Description

int64_t

The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Input buffer isn't large enough to possibly contain a valid STArray. DOESNT_EXIST - The searched for index isn't present in the supplied STArray. PARSE_ERROR - The supplied STArray is malformed or not an STArray.

sto_emplace

Emplace a field into an existing STObject at its canonical placement

Concepts

Serialized Objects

Behaviour

Parse an STObject S (source object) pointed to by sread_ptr
Parse an STObject F (to inject/emplace) pointed to by fread_ptr
Write a new STObject to write_ptr which places F into S at the canonical position field_id

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_emplace (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t fread_ptr,
    uint32_t fread_len,
  	uint32_t field_id
);

Example

uint8_t tx_out[1024];

int64_t tx_len =
    sto_emplace(tx_out, sizeof(tx_out),
                tx_in, tx_len,
                sequence_field, 5, sfSequence);

if (tx_len <= 0)
    rollback("Emplacing failed.", 17, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

sread_ptr

uint32_t

The buffer to read the source STObject from

sread_len

uint32_t

The Length of the source object

fread_ptr

uint32_t

The buffer to read the field to be emplaced/injected from

fread_len

uint32_t

The length of the field to be emplaced/injected

field_id

uint32_t

The sf code (location) to form the emplacement. If this already exists in the source object then the existing field is overriden. If it doesn't exist it is inserted.

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object + the injected field, even if the field is only being overriden. TOO_BIG - Field you are attempting to emplace is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject.

sto_erase

Remove a field from an STObject

Concepts

Serialized Objects

Behaviour

Parse an STObject pointed to by read_ptr
Write a new STObject to write_ptr but without field_id if it was present in the original object.

Definition

int64_t sto_erase (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len,
  	uint32_t field_id
);

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Example

int64_t result = 
  sto_erase(tx_out, sizeof(tx_out),
            tx_in, tx_len, sfSigners);

if (tx_len <= 0)
    rollback("Erasing failed.", 15, 1);

📘Emplace equivalence
sto_erase is the same as sto_emplace with 0,0 for field_ptr, field_len parameters.

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

read_ptr

uint32_t

The buffer to read the source STObject from

read_len

uint32_t

The Length of the source object

field_id

uint32_t

The sf code (location) to erase

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object. TOO_BIG - Field you are attempting to erase from is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject. DOESNT_EXIST - The specified field_id isn't present in the STObject.

sto_validate

Validate an STObject

Concepts

Serialized Objects

Behaviour

Parse an STObject pointed to by read_ptr
Return 1 if the serialization is valid, 0 otherwise.

Definition

int64_t sto_validate (
    uint32_t read_ptr,
    uint32_t read_len
);

Example

int64_t result = 
  sto_validate(tx_out, sizeof(tx_out));

if (tx_len <= 0)
    rollback("Invalid STO.", 12, 1);

Parameters

Name

Type

Description

read_ptr

uint32_t

The buffer to read the source STObject from

read_len

uint32_t

The Length of the source object

Return Code

Type

Description

int64_t

1 if the STObject pointed to by read_ptr is a valid STObject. 0 if it isn't. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

sto_emplace

Emplace a field into an existing STObject at its canonical placement

Concepts

Serialized Objects

Behaviour

Parse an STObject S (source object) pointed to by sread_ptr
Parse an STObject F (to inject/emplace) pointed to by fread_ptr
Write a new STObject to write_ptr which places F into S at the canonical position field_id

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_emplace (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t fread_ptr,
    uint32_t fread_len,
  	uint32_t field_id
);

Example

uint8_t tx_out[1024];

int64_t tx_len =
    sto_emplace(tx_out, sizeof(tx_out),
                tx_in, tx_len,
                sequence_field, 5, sfSequence);

if (tx_len <= 0)
    rollback("Emplacing failed.", 17, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

sread_ptr

uint32_t

The buffer to read the source STObject from

sread_len

uint32_t

The Length of the source object

fread_ptr

uint32_t

The buffer to read the field to be emplaced/injected from

fread_len

uint32_t

The length of the field to be emplaced/injected

field_id

uint32_t

The sf code (location) to form the emplacement. If this already exists in the source object then the existing field is overriden. If it doesn't exist it is inserted.

Return Code

Type

Description

int64_t

sto_erase

Remove a field from an STObject

Concepts

Serialized Objects

Behaviour

Parse an STObject pointed to by read_ptr
Write a new STObject to write_ptr but without field_id if it was present in the original object.

Definition

int64_t sto_erase (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len,
  	uint32_t field_id
);

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Example

int64_t result = 
  sto_erase(tx_out, sizeof(tx_out),
            tx_in, tx_len, sfSigners);

if (tx_len <= 0)
    rollback("Erasing failed.", 15, 1);

📘Emplace equivalence
sto_erase is the same as sto_emplace with 0,0 for field_ptr, field_len parameters.

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

read_ptr

uint32_t

The buffer to read the source STObject from

read_len

uint32_t

The Length of the source object

field_id

uint32_t

The sf code (location) to erase

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object. TOO_BIG - Field you are attempting to erase from is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject. DOESNT_EXIST - The specified field_id isn't present in the STObject.

sto_subfield

Index into a xahaud serialized object and return the location and length of a subfield

Concepts

Serialized Objects

Behaviour

Parse a STObject pointed to by read_ptr
Find the field specified by field_id
If the field is found, and:
1. It is an array, then return the start and length of the array including the leadin/leadout bytes, or
1. It is not an array, then return the start and length of the PAYLOAD of the field (excluding the leadin bytes).

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_subfield (
    uint32_t read_ptr,
  	uint32_t read_len,
  	uint32_t field_id
);

Example

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
int64_t memo_lookup =
    sto_subfield(memo_ptr, memo_len, sfMemo);
if (memo_lookup < 0)
{
    // sfMemo was not found in the STObject pointed at by memo_ptr
}
else
{
    // sfMemo was found and its location is as follows:
	  uint8_t* memo_ptr = SUB_OFFSET(memo_lookup) + memo_ptr;
	  int64_t  memo_len = SUB_LENGTH(memo_lookup);
}

📘
hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the STObject

read_len

uint32_t

Length of STObject

field_id

uint32_t

Return Code

Type

Description

int64_t