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

What’s Next