Weak and Strong

Which Hooks are allowed to run and when?

👍

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.

For example:

• 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.

Weak and Strong

Each TSH has either a weak or a strong connection to the transaction.

A Strong connection means:

1. The originating transaction must pay the fee for the execution of the TSH Hook Chain
2. The TSH has the right to rollback the whole transaction by calling rollback() from their Hook during execution.

A Weak connection means:

1. The originating transaction does not pay for the execution of the TSH Hook Chain.
2. The TSH pays for the execution of their own Hook Chain through a feature called Collect Call Hooks.
3. The TSH must have set an account flag asfTshCollect prior to the execution of the originating transaction.
4. 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.)

Before or After

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.

📘

Hint

Strongly executed hooks can call hook_again to be executed a second time as a weak execution after the originating transaction has been applied.

Execution Context

The uint32_t parameter in hook(uint32_t) and cbak(uint32_t) carries important context information from the Hooks Amendment to your Hook.

During the execution of hook:

• 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 cbak:

• 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).

Reference Table

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.
EscrowCreate	Strong	Destination account
EscrowFinish	Strong	Destination account
EscrowCancel	Weak	Destination account
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.
PaymentChannelCreate	Strong	Destination account
PaymentChannelFund	Weak	Destination account
PaymentChannelClaim	Weak	Destination account
CheckCreate	Strong	Destination account
CheckCash	Strong	Destination account
CheckCancel	Weak	Destination account
DepositPreauth	Strong	Authorised account
TrustSet	Weak	Issuer account
AccountDelete	Strong	Destination account funds are paid out to after deletion
NFTokenMint	Strong	Issuer account (if any)
NFTokenBurn	Weak	Owner account (if any), Issuer account
NFTokenCreateOffer	Strong	Owner account (if any), Issuer account
NFTokenCancelOffer	Weak	Owner account, Destination account
NFTokenAcceptOffer	Strong	Where each is applicable: - buy offer Owner account - buy offer Destination account - sell offer Owner account - sell offer Destination account