From 4eea0bf01c815955b5917fc6026ddf393d7e1619 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ekiserrep=C3=A9?= <126416117+Ekiserrepe@users.noreply.github.com> Date: Tue, 23 Jun 2026 16:32:35 +0200 Subject: [PATCH] Emit/Prepare update --- src/content/docs/docs/features/amendments.mdx | 2 +- .../network-features/balance-rewards.mdx | 1 - .../functions/emitted-transaction/emit-1.mdx | 114 ---------------- .../functions/emitted-transaction/emit.mdx | 83 +++++------- .../functions/emitted-transaction/prepare.mdx | 125 ++++++++++++++++++ 5 files changed, 162 insertions(+), 163 deletions(-) delete mode 100644 src/content/docs/docs/hooks/functions/emitted-transaction/emit-1.mdx create mode 100644 src/content/docs/docs/hooks/functions/emitted-transaction/prepare.mdx diff --git a/src/content/docs/docs/features/amendments.mdx b/src/content/docs/docs/features/amendments.mdx index dc027c0..b6e9f96 100644 --- a/src/content/docs/docs/features/amendments.mdx +++ b/src/content/docs/docs/features/amendments.mdx @@ -197,7 +197,7 @@ A port of the XRPL PriceOracle (XLS-47d) standard. Enables on-chain price feeds ##### IOURewardClaim -Expands the [ClaimReward](/docs/protocol-reference/transactions/transaction-types/claimreward) transaction type beyond genesis balance adjustments to issuers of other IOU currencies. The same reward logic (area under the curve of hold time vs. hold amount) is optionally applied to issuer currencies using the `ClaimCurrency` field. Reward counters are held within the trustline (`LowReward`/`HighReward` objects on the [RippleState](/docs/protocol-reference/ledger-data/ledger-objects-types/ripple-state) object) and do not affect genesis balance adjustments. The actual reward payout is handled by a Hook installed on the issuer account that fires on `ttCLAIM_REWARD`. _(Introduced in 2026.6.21-release+3350)_ +Expands the [ClaimReward](/docs/protocol-reference/transactions/transaction-types/claimreward) transaction type beyond genesis balance adjustments to issuers of other IOU currencies. Reward counters are held within the trustline (`LowReward`/`HighReward` objects on the [RippleState](/docs/protocol-reference/ledger-data/ledger-objects-types/ripple-state) object) and do not affect genesis balance adjustments. The transaction triggers any Hook installed on the account specified by the `Issuer` field, allowing that Hook to process and optionally pay out the reward. The reward-paying account does not need to be the issuer of the IOU currency. _(Introduced in 2026.6.21-release+3350)_ ##### fixCronStacking diff --git a/src/content/docs/docs/features/network-features/balance-rewards.mdx b/src/content/docs/docs/features/network-features/balance-rewards.mdx index e6e56f0..16fe578 100644 --- a/src/content/docs/docs/features/network-features/balance-rewards.mdx +++ b/src/content/docs/docs/features/network-features/balance-rewards.mdx @@ -39,5 +39,4 @@ The `IOURewardClaim` amendment extends the reward mechanic to IOU currencies iss | Counters stored on | AccountRoot | RippleState (trustline) | | Accumulator type | UInt64 (drops / 1,000,000) | Amount (in the token's units) | | Payout handled by | Genesis account Hook | Issuer account Hook | -| Opt-out flag | `tfOptOut` (flag 1) | Not applicable | | Issuer restriction | Must be genesis account | Any account with a Hook on `ttCLAIM_REWARD`, except AMM accounts | diff --git a/src/content/docs/docs/hooks/functions/emitted-transaction/emit-1.mdx b/src/content/docs/docs/hooks/functions/emitted-transaction/emit-1.mdx deleted file mode 100644 index 721dfda..0000000 --- a/src/content/docs/docs/hooks/functions/emitted-transaction/emit-1.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: emit -description: Emit a new transaction from the hook ---- -import { Tabs, TabItem, LinkButton } from '@astrojs/starlight/components'; - -### Concepts - -Emitted Transactions -prepare() - -### Behaviour - - - -* Read a transaction from `read_ptr` -* Validate the transaction against the emission rules -* Emit the transaction into consensus when valid -* Write canonical transaction hash to `write_ptr` - -With the [HooksUpdate2 amendment](/docs/features/amendments/#hooksupdate2), use [`prepare()`](/docs/hooks/functions/emitted-transaction/emit) before `emit()` to automatically inject all required emission fields (`Account`, `Sequence`, `SigningPubKey`, `Fee`, `EmitDetails`, etc.) from a partial transaction. - - - -* This function emits the provided transaction JSON. -* On success, it returns the number of emitted transaction hashes. -* If there is an error, it returns an error code. - - - -### Definition - - - -```c -int64_t emit ( - uint32_t write_ptr, - uint32_t write_len, - uint32_t read_ptr, - uint32_t read_len -); -``` - - - - - -```javascript -function emit( - txJson: Record | Transaction - ): ErrorCode | ByteArray -``` - - - - - -### Example - - - -```c -if (emit(tx, tx_len) < 0) - rollback("Failed to emit!", 15, 1); -``` - - - - - -```javascript -const emitResult = emit(txJson) -if(typeof emitResult === 'number') - rollback("Failed to emit!", 1) -``` - - - - - -### Parameters - - - -
NameTypeDescription
write_ptruint32_tPointer to a buffer to write the transaction hash to
write_lenuint32_tThe size of the buffer to write the transaction hash to (should be 32.)
read_ptruint32_tPointer to the transaction to emit
read_lenuint32_tThe length of the transaction
- - - - - - - -
NameTypeDescription
txJsonRecord<string, any> | TransactionThe TX JSON to emit.
- - - - - -### Return Code - - - -
TypeDescription
int64_tOn success, the number of bytes of transaction hash written (32), or:

If negative, an error:
OUT_OF_BOUNDS
- pointers/lengths specified outside of hook memory.

PREREQUISITE_NOT_MET
- emit_reserve must be called first

TOO_MANY_EMITTED_TXN
- the number of emitted transactions is now greater than the promise made when emit_reserve was called earlier

EMISSION_FAILURE
- the transaction was malformed according to the emission rules.
- - - - - - - -
TypeDescription
ErrorCode | ByteArrayReturns an ErrorCode if there is an error, or an array of emitted transaction hashes on success.
- - - diff --git a/src/content/docs/docs/hooks/functions/emitted-transaction/emit.mdx b/src/content/docs/docs/hooks/functions/emitted-transaction/emit.mdx index a5db7b4..721dfda 100644 --- a/src/content/docs/docs/hooks/functions/emitted-transaction/emit.mdx +++ b/src/content/docs/docs/hooks/functions/emitted-transaction/emit.mdx @@ -1,30 +1,30 @@ --- -title: prepare -description: Prepares a transaction for emission by automatically injecting all required emission fields. +title: emit +description: Emit a new transaction from the hook --- import { Tabs, TabItem, LinkButton } from '@astrojs/starlight/components'; ### Concepts Emitted Transactions +prepare() ### Behaviour +* Read a transaction from `read_ptr` +* Validate the transaction against the emission rules +* Emit the transaction into consensus when valid +* Write canonical transaction hash to `write_ptr` -_(Requires the [HooksUpdate2 amendment](/docs/features/amendments/#hooksupdate2).)_ - -* 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 **must not** include emission-specific fields. -* 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()`](/docs/hooks/functions/emitted-transaction/emit-1). -* `etxn_reserve()` must be called before `prepare()`. +With the [HooksUpdate2 amendment](/docs/features/amendments/#hooksupdate2), use [`prepare()`](/docs/hooks/functions/emitted-transaction/emit) before `emit()` to automatically inject all required emission fields (`Account`, `Sequence`, `SigningPubKey`, `Fee`, `EmitDetails`, etc.) from a partial transaction. -* This function takes a transaction JSON object and prepares it for emission. -* The transaction must be complete except for the Account field, which should always be the Hook account. +* This function emits the provided transaction JSON. +* On success, it returns the number of emitted transaction hashes. +* If there is an error, it returns an error code. @@ -33,93 +33,82 @@ _(Requires the [HooksUpdate2 amendment](/docs/features/amendments/#hooksupdate2) ```c -int64_t prepare ( +int64_t emit ( uint32_t write_ptr, uint32_t write_len, uint32_t read_ptr, uint32_t read_len ); ``` + + ```javascript -function prepare( +function emit( txJson: Record | Transaction - ): ErrorCode | Record | Transaction + ): ErrorCode | ByteArray ``` + + ### Example ```c -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); +if (emit(tx, tx_len) < 0) + rollback("Failed to emit!", 15, 1); ``` + + ```javascript -const prepared_txn = prepare({ - TransactionType: "Payment", - Destination: util_raddr(p1address_ns), - Amount: parseFloat(drops_sent)*2 - }) +const emitResult = emit(txJson) +if(typeof emitResult === 'number') + rollback("Failed to emit!", 1) ``` + + ### Parameters +
NameTypeDescription
write_ptruint32_tPointer to a buffer to write the transaction hash to
write_lenuint32_tThe size of the buffer to write the transaction hash to (should be 32.)
read_ptruint32_tPointer to the transaction to emit
read_lenuint32_tThe length of the transaction
-| 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. | -
NameTypeDescription
txJsonRecord<string, any> | TransactionThe transaction JSON, must be a complete transaction except for Account (always the Hook account).
+ +
NameTypeDescription
txJsonRecord<string, any> | TransactionThe TX JSON to emit.
 + + ### Return Code +
TypeDescription
int64_tOn success, the number of bytes of transaction hash written (32), or:

If negative, an error:
OUT_OF_BOUNDS
- pointers/lengths specified outside of hook memory.

PREREQUISITE_NOT_MET
- emit_reserve must be called first

TOO_MANY_EMITTED_TXN
- the number of emitted transactions is now greater than the promise made when emit_reserve was called earlier

EMISSION_FAILURE
- the transaction was malformed according to the emission rules.
-| Type | Description | -| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| int64_t | On success, the number of bytes written to `write_ptr` (the size of the prepared transaction blob). The result can be passed directly as `read_ptr`/`read_len` to `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. | -
TypeDescription
ErrorCode | Record<string, any> | TransactionReturns an ErrorCode if there is an error, or the prepared transaction JSON or Transaction object.
+ +
TypeDescription
ErrorCode | ByteArrayReturns an ErrorCode if there is an error, or an array of emitted transaction hashes on success.
 + diff --git a/src/content/docs/docs/hooks/functions/emitted-transaction/prepare.mdx b/src/content/docs/docs/hooks/functions/emitted-transaction/prepare.mdx new file mode 100644 index 0000000..4387d2c --- /dev/null +++ b/src/content/docs/docs/hooks/functions/emitted-transaction/prepare.mdx @@ -0,0 +1,125 @@ +--- +title: prepare +description: Prepares a transaction for emission by automatically injecting all required emission fields. +--- +import { Tabs, TabItem, LinkButton } from '@astrojs/starlight/components'; + +### Concepts + +Emitted Transactions + +### Behaviour + + + + +_(Requires the [HooksUpdate2 amendment](/docs/features/amendments/#hooksupdate2).)_ + +* 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()`](/docs/hooks/functions/emitted-transaction/emit-1). +* `etxn_reserve()` must be called before `prepare()`. + + + +* This function takes a transaction JSON object and prepares it for emission. +* The transaction must be complete except for the Account field, which should always be the Hook account. + + + +### Definition + + + +```c +int64_t prepare ( + uint32_t write_ptr, + uint32_t write_len, + uint32_t read_ptr, + uint32_t read_len +); +``` + + + +```javascript +function prepare( + txJson: Record | Transaction + ): ErrorCode | Record | Transaction +``` + + + +### Example + + + +```c +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); +``` + + + +```javascript +const prepared_txn = prepare({ + TransactionType: "Payment", + Destination: util_raddr(p1address_ns), + Amount: parseFloat(drops_sent)*2 + }) +``` + + + +### Parameters + + + + +| 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. | + + + + + +
NameTypeDescription
txJsonRecord<string, any> | TransactionThe transaction JSON, must be a complete transaction except for Account (always the Hook account).
+ + + +### Return Code + + + + +| Type | Description | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| int64_t | On success, the number of bytes written to `write_ptr` (the size of the prepared transaction blob). The result can be passed directly as `read_ptr`/`read_len` to `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. | + + + + + +
TypeDescription
ErrorCode | Record<string, any> | TransactionReturns an ErrorCode if there is an error, or the prepared transaction JSON or Transaction object.
+ +