Weak and Strong

👍 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 XAH 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 Xahau, 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.

AccountSet

AccountDelete

Check

ClaimReward

DepositPreauth

Escrow

GenesisMint

Import

Invoke

Offer

Payment

PaymentChannel

SetHook

SetRegularKey

SignersListSet

Ticket

TrustSet

URIToken