Hook Design Philosophy
Every party affected by a transaction should have the opportunity to have their Hooks executed.
Transactional Stake Holders (TSH) are parties that somehow have a stake in or are otherwise affected by a transaction. Their particular stake may be a weak or strong. The degree of connection with the transaction dictates whether the party has the right to have their Hooks executed and who has to pay for that execution.
- In a conventional direct XRP Payment transaction the two TSH are the originating account and the destination account.
- In a SetSignerList transaction the TSH are the originating account and each account whose address appears in the signer list, where such accounts are active on the ledger.
- In an OfferCreate transaction, other account's offers which are crossed by the originating transaction are all weak TSH and may opt for weak execution.
Due to the heterogenous nature of transactions on the XRP Ledger, TSH come in all shapes and sizes and can be exotic and non-intuitive. This becomes more true as time passes and more transaction types are added to the Ledger.
Each TSH has either a weak or a strong connection to the transaction.
A Strong connection means:
- The originating transaction must pay the fee for the execution of the TSH Hook Chain
- The TSH has the right to rollback the whole transaction by calling
rollback()from their Hook during execution.
A Weak connection means:
- The originating transaction does not pay for the execution of the TSH Hook Chain.
- The TSH pays for the execution of their own Hook Chain through a feature called Collect Call Hooks.
- The TSH must have set an account flag
asfTshCollectprior to the execution of the originating transaction.
- The TSH does not have the right to rollback the whole transaction by calling
rollback()from their Hook during execution (but can still modify their own Hook state and Emit transactions.)
Strong TSHes have their hooks executed before the originating transaction is applied to the ledger. This means they have the ability to rollback the transaction (because it hasn't yet been applied.) This gives strongly executed hooks the ability to completely block a transaction from occurring.
Weak TSHes have their hooks executed after the originating transaction has been applied to the ledger. This means they have access to the transaction metadata but cannot prevent the transaction from occurring.
Strongly executed hooks can call hook_again to be executed a second time as a weak execution after the originating transaction has been applied.
uint32_t parameter in
cbak(uint32_t) carries important context information from the Hooks Amendment to your Hook.
During the execution of
- 0 means the Hook is being executed strongly
- 1 means the Hook is being executed weakly
- 2 means the Hook is being executed weakly after being executed strongly due to a hook_again call.
During the execution of
- 0 means the Hook is being called back after a transaction it emitted was successfully accepted into a ledger.
- 1 means the Hook is being called back after a transaction it emitted was marked as never able to be applied to any ledger (EmitFailure).
If a Transaction Type does not appear in the table then it has no TSHes other than its originating account.
|Transaction Type||TSH Type||Who is the TSH|
|Payment||Strong + Weak||Strong: Destination account.|
Weak: Any non-issuer the payment is rippled through.
|OfferCreate||Weak||Accounts whose offers were crossed by this action.|
|SignerListSet||Strong||Accounts whose addresses are set as signing keys (if they exist and have Hooks set on them).|
|SetRegularKey||Strong||The account whose address is being set as the key.|
|AccountDelete||Strong||Destination account funds are paid out to after deletion|
|URITokenBurn||Strong||Issuer if tfBurnable Flag is set|
|URITokenBuy||Strong||Owner account, Issuer if tfBurnable Flag is set|
|URITokenCreateSellOffer||Strong||Destination account, Issuer if tfBurnable Flag is set|
Updated 2 months ago