vbar

#include "hookapi.h"

/**
 * @invoke ttPAYMENT ttACCOUNT_SET
 * @field admin
 */

int64_t hook(uint32_t reserved)
{
    // check for the presence of a memo

vbar

Peggy hook provides an automated way to issue and redeem an over-collateralised XRP-backed stablecoin.

Sending XRP to it creates a vault and sends back stablecoin, which can be redeemed against the vault to get back the original XRP.

The exchange rate between XRP and stablecoin is the limit set on a trustline established between two special oracle accounts.

If the value of XRP falls too far, the vault gets under a minimum collateralization threshold. This means anyone who wants to top up the vault above the threshold can come along and take it over.

to test:

• make sure Hooks Builder has at least 5 accounts: Alice, Bob, Carol, Carlos and Charlie

vbar

Notary hook collects signatures for multi-sign transactions. It has two modes of operation:

1. Attach a proposed transaction to a memo and send it to the hook account
2. Endorse an already proposed transaction by using its unique ID as invoice ID and sending a 1 drop payment to the hook.

It relies on the signer list on the account the hook is running on. Only accounts on this list can propose and endorse multisign transactions through this hook.

to test:

• make sure Hooks Builder has at least 3 accounts: Alice, Bob and Carol
• set up SignerListSet on Alice's account w/ SignerQuorum 2 to Bob & Carol
• compile notary.c and deploy it to Alice account

vbar

Firewall is an example of cooperating hooks: firewall hook instances filter incoming payments, based on shared state maintained by blacklist hook.

To cooperate, the hooks need information about each other, which must be obtained before deploying them, because it's passed to them as install-time parameters.

to test:

• make sure Hooks Builder has at least 4 accounts: Alice, Bob, Carol and Carlos
• run key.js to get a public key of the blacklist admin account, e.g. Alice; it asks for that account's secret key
  • verify the script is using it just to derive the public key
  • if you don't believe the script, or its dependencies, do the conversion in a trusted environment
• compile blacklist.c and deploy it to Bob account

vbar

Carbon hook sends a percentage of outgoing payments to a dedicated account.

The beneficiary account is hard-coded, so while the default version of carbon.c works, it works with an account that cannot be imported into Hooks Builder (unless you know its secret key). See later examples for how to parametrize a hook.

to test:

• make sure Hooks Builder has at least 3 accounts: Alice, Bob and Carol
• in carbon.c, change hardcoded beneficiary to Carol account
• compile carbon.c and deploy it to Alice account
• set up payment transaction from Alice to Bob
• open debug stream filtered on Carol

vbar

Starter is the simplest possible hook: it just accepts all transactions and logs that it is running.

to test:

• in the develop pane, compile starter.c
• in the deploy pane, deploy it to Alice account
• set up payment transaction from Alice to Bob
• run it and see in the debug stream 'Accept.c: Called.'

Modifying the tracing message and compiling with different optimizations are left as an exercise for the reader.