prepare

Concepts

Behaviour

C
JavaScript

(Requires the HooksUpdate2 amendment.)

Reads a partial serialized transaction from read_ptr/read_len. The input must contain at minimum the TransactionType and all fields required by that transaction type, but included emission-specific fields will be overwritten.
Automatically injects all fields required for emission: Account (the Hook account), Sequence (0), SigningPubKey (all zeros), Fee (computed), FirstLedgerSequence (current ledger + 1), LastLedgerSequence (current ledger + 5), and EmitDetails.
Writes the complete, emission-ready transaction blob to write_ptr.
The output can be passed directly to emit().
etxn_reserve() must be called before prepare().

int64_t prepare (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len
);

function prepare(
    txJson: Record<string, any> | Transaction
  ): ErrorCode | Record<string, any> | Transaction

Example

C
JavaScript

etxn_reserve(1);

// Build a minimal payment transaction (TransactionType + required fields only)
uint8_t tx[256];
// ... populate tx with TransactionType, Destination, Amount ...
int64_t tx_len = /* size of tx */;

// prepare() fills in Account, Sequence, Fee, EmitDetails, etc.
uint8_t prepared[512];
int64_t prepared_len = prepare(prepared, sizeof(prepared), tx, tx_len);
if (prepared_len < 0)
    rollback("Prepare failed", 14, prepared_len);

// emit() submits the fully-formed transaction
uint8_t txid[32];
if (emit(txid, 32, prepared, prepared_len) != 32)
    rollback("Emit failed", 11, EMISSION_FAILURE);

const prepared_txn = prepare({
                TransactionType: "Payment",
                Destination: util_raddr(p1address_ns),
                Amount: parseFloat(drops_sent)*2
            })

Parameters

C
JavaScript

Name	Type	Description
`write_ptr`	uint32_t	Pointer to a buffer to receive the complete prepared transaction blob.
`write_len`	uint32_t	Length of the write buffer. Must be large enough to hold the prepared transaction (input size + injected fields).
`read_ptr`	uint32_t	Pointer to a partial serialized transaction. Must include `TransactionType` and all type-specific required fields.
`read_len`	uint32_t	Length of the input transaction.

Name	Type	Description
txJson	Record<string, any> \| Transaction	The transaction JSON, must be a complete transaction except for Account (always the Hook account).

Return Code

C
JavaScript

Type Description

int64_t On success, the number of bytes written to write_ptr (the size of the prepared transaction blob). The returned value is the length of the prepared transaction. Pass the original buffer as read_ptr and the returned length as read_len when calling emit().

If negative, an error:
OUT_OF_BOUNDS — pointers/lengths fall outside hook memory.
PREREQUISITE_NOT_MET — etxn_reserve() must be called before prepare().
INVALID_ARGUMENT — the input blob is not a valid serialized transaction, or the transaction cannot be prepared (e.g. fee computation failed).
INTERNAL_ERROR — failed to generate EmitDetails or re-serialize the transaction.

Type	Description
int64_t	On success, the number of bytes written to `write_ptr` (the size of the prepared transaction blob). The returned value is the length of the prepared transaction. Pass the original buffer as `read_ptr` and the returned length as `read_len` when calling `emit()`. If negative, an error: `OUT_OF_BOUNDS` — pointers/lengths fall outside hook memory. `PREREQUISITE_NOT_MET` — `etxn_reserve()` must be called before `prepare()`. `INVALID_ARGUMENT` — the input blob is not a valid serialized transaction, or the transaction cannot be prepared (e.g. fee computation failed). `INTERNAL_ERROR` — failed to generate `EmitDetails` or re-serialize the transaction.