ARCHIVE/xahaud
3
0
Fork 0
mirror of https://github.com/Xahau/xahaud.git synced 2025-12-01 16:05:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

examples and tests WIP

Browse Source
This commit is contained in:
Richard Holland
2022-02-18 12:41:52 +00:00
parent e0fa4b4f1f
commit 9325e11b14
34 changed files with 2339 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
hook-api-examples/accept/accept.c Normal file
View File

@@ -0,0 +1,18 @@
/**
* This hook just accepts any transaction coming through it
*/
#include "../hookapi.h"
int64_t cbak(uint32_t reserved) {
return 0;
}
int64_t hook(uint32_t reserved ) {
TRACESTR("Accept.c: Called.");
accept (0,0,0);
_g(1,1); // every hook needs to import guard function and use it at least once
// unreachable
return 0;
}

43
hook-api-examples/accept/install.js Normal file
View File

@@ -0,0 +1,43 @@
if (process.argv.length < 3)
{
console.log("Usage: node accept <account family seed>")
process.exit(1);
}
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
let wasm = t.findWasm();
if (wasm.length != 1)
{
console.log("There should be exactly one .wasm file in the current working directory.")
console.log("Try make")
process.exit(1);
}
const secret = process.argv[2];
const account = t.xrpljs.Wallet.fromSeed(secret)
t.api.submit(
{
Account: account.classicAddress,
TransactionType: "SetHook",
Hooks: [
{
Hook: {
CreateCode: t.wasm(wasm[0]),
HookApiVersion: 0,
HookNamespace: "CAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFE",
HookOn: "0000000000000000",
Flags: t.hsfOVERRIDE
}
}
],
Fee: "100000"
}, {wallet: account}).then(x=>
{
t.assertTxnSuccess(x)
console.log(x);
process.exit(0);
}).catch(e=>console.log(e));
}).catch(e=>console.log(e));

3
hook-api-examples/accept/makefile Normal file
View File

@@ -0,0 +1,3 @@
all:
wasmcc accept.c -o accept.wasm -O0 -Wl,--allow-undefined -I../

19
hook-api-examples/accept/pay.js Normal file
View File

@@ -0,0 +1,19 @@
if (process.argv.length < 5)
{
console.log("Usage: node pay <source family seed> <amount xrp> <destination account>")
process.exit(1)
}
const secret = process.argv[2];
const amount = BigInt(process.argv[3]) * 1000000n
const dest = process.argv[4];
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
t.pay(secret, amount, dest).then(x=>
{
console.log(x);
process.exit(0);
});
});

98
hook-api-examples/carbon/carbon.c Normal file
View File

@@ -0,0 +1,98 @@
#include <stdint.h>
#include "../hookapi.h"
int64_t cbak(uint32_t reserved)
{
TRACESTR("Carbon: callback called.");
return 0;
}
int64_t hook(uint32_t reserved)
{
TRACESTR("Carbon: started");
// before we start calling hook-api functions we should tell the hook how many tx we intend to create
etxn_reserve(1); // we are going to emit 1 transaction
// this api fetches the AccountID of the account the hook currently executing is installed on
// since hooks can be triggered by both incoming and ougoing transactions this is important to know
unsigned char hook_accid[20];
hook_account((uint32_t)hook_accid, 20);
// NB:
// almost all of the hook apis require a buffer pointer and buffer length to be supplied ... to make this a
// little easier to code a macro: `SBUF(your_buffer)` expands to `your_buffer, sizeof(your_buffer)`
// next fetch the sfAccount field from the originating transaction
uint8_t account_field[20];
int32_t account_field_len = otxn_field(SBUF(account_field), sfAccount);
TRACEVAR(account_field_len);
if (account_field_len < 20) // negative values indicate errors from every api
rollback(SBUF("Carbon: sfAccount field missing!!!"), 1); // this code could never be hit in prod
// but it's here for completeness
// compare the "From Account" (sfAccount) on the transaction with the account the hook is running on
int equal = 0; BUFFER_EQUAL(equal, hook_accid, account_field, 20);
if (!equal)
{
// if the accounts are not equal (memcmp != 0) the otxn was sent to the hook account by someone else
// accept() it and end the hook execution here
accept(SBUF("Carbon: Incoming transaction"), 2);
}
// execution to here means the user has sent a valid transaction FROM the account the hook is installed on
// fetch the sent Amount
// Amounts can be 384 bits or 64 bits. If the Amount is an XRP value it will be 64 bits.
unsigned char amount_buffer[48];
int64_t amount_len = otxn_field(SBUF(amount_buffer), sfAmount);
int64_t drops_to_send = 1000; // this will be the default
if (amount_len != 8)
{
// you can trace the behaviour of your hook using the trace(buf, size, as_hex) api
// which will output to xrpld's trace log
TRACESTR("Carbon: Non-xrp transaction detected, sending default 1000 drops to rfCarbon");
} else
{
TRACESTR("Carbon: XRP transaction detected, computing 1% to send to rfCarbon");
int64_t otxn_drops = AMOUNT_TO_DROPS(amount_buffer);
TRACEVAR(otxn_drops);
if (otxn_drops > 100000) // if its less we send the default amount. or if there was an error we send default
drops_to_send = (int64_t)((double)otxn_drops * 0.01f); // otherwise we send 1%
}
TRACEVAR(drops_to_send);
// hooks communicate accounts via the 20 byte account ID, this can be generated from an raddr like so
// a more efficient way to do this is precompute the account-id from the raddr (if the raddr never changes)
uint8_t carbon_accid[20];
int64_t ret = util_accid(
SBUF(carbon_accid), /* <-- generate into this buffer */
SBUF("rfCarbonVNTuXckX6x2qTMFmFSnm6dEWGX") ); /* <-- from this r-addr */
TRACEVAR(ret);
// fees for emitted transactions are based on how many txn your hook is emitted, whether or not this triggering
// was caused by a previously emitted transaction and how large the new emitted transaction is in bytes
// we need to precompute this before populating the payment transaction, as it is a field inside the tx
int64_t fee_base = etxn_fee_base(PREPARE_PAYMENT_SIMPLE_SIZE);
// create a buffer to write the emitted transaction into
unsigned char tx[PREPARE_PAYMENT_SIMPLE_SIZE];
// we will use an XRP payment macro, this will populate the buffer with a serialized binary transaction
// Parameter list: ( buf_out, drops_amount, drops_fee, to_address, dest_tag, src_tag )
PREPARE_PAYMENT_SIMPLE(tx, drops_to_send++, fee_base, carbon_accid, 0, 0);
// emit the transaction
uint8_t emithash[32];
int64_t emit_result = emit(SBUF(emithash), SBUF(tx));
TRACEVAR(emit_result);
// accept and allow the original transaction through
accept(SBUF("Carbon: Emitted transaction"), 0);
return 0;
}

43
hook-api-examples/carbon/install.js Normal file
View File

@@ -0,0 +1,43 @@
if (process.argv.length < 3)
{
console.log("Usage: node accept <account family seed>")
process.exit(1);
}
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
let wasm = t.findWasm();
if (wasm.length != 1)
{
console.log("There should be exactly one .wasm file in the current working directory.")
console.log("Try make")
process.exit(1);
}
const secret = process.argv[2];
const account = t.xrpljs.Wallet.fromSeed(secret)
t.api.submit(
{
Account: account.classicAddress,
TransactionType: "SetHook",
Hooks: [
{
Hook: {
CreateCode: t.wasm(wasm[0]),
HookApiVersion: 0,
HookNamespace: "CAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFE",
HookOn: "0000000000000000",
Flags: t.hsfOVERRIDE
}
}
],
Fee: "100000"
}, {wallet: account}).then(x=>
{
t.assertTxnSuccess(x)
console.log(x);
process.exit(0);
}).catch(e=>console.log(e));
}).catch(e=>console.log(e));

3
hook-api-examples/carbon/makefile Normal file
View File

@@ -0,0 +1,3 @@
all:
wasmcc carbon.c -o carbon.wasm -O0 -Wl,--allow-undefined -I../

19
hook-api-examples/carbon/pay.js Normal file
View File

@@ -0,0 +1,19 @@
if (process.argv.length < 5)
{
console.log("Usage: node pay <source family seed> <amount xrp> <destination account>")
process.exit(1)
}
const secret = process.argv[2];
const amount = BigInt(process.argv[3]) * 1000000n
const dest = process.argv[4];
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
t.pay(secret, amount, dest).then(x=>
{
console.log(x);
process.exit(0);
});
});

77
hook-api-examples/doubler/doubler.c Normal file
View File

@@ -0,0 +1,77 @@
//Authors: NeilH, RichardAH
// (joke) test hook that doubles incoming XRP payments and sends it back
// April 1st 2021: Added (unfair) coin flip
#include <stdint.h>
#include "../hookapi.h"
int64_t cbak(uint32_t reserved)
{
return 0;
}
int64_t hook(uint32_t reserved)
{
uint8_t hook_accid[20];
if (hook_account(SBUF(hook_accid)) < 0)
rollback(SBUF("Doubler: Could not fetch hook account id."), 1);
// next fetch the sfAccount field from the originating transaction
uint8_t account_field[20];
int32_t account_field_len = otxn_field(SBUF(account_field), sfAccount);
// compare the "From Account" (sfAccount) on the transaction with the account the hook is running on
int equal = 0; BUFFER_EQUAL(equal, hook_accid, account_field, 20);
if (equal)
{
accept(SBUF("Doubler: Outgoing transaction. Passing."), 2);
return 0;
}
uint8_t digest[96];
if (ledger_last_hash(digest, 32) != 32)
rollback(SBUF("Doubler: Failed to fetch last closed ledger."), 3);
uint8_t key[32]; // left as 0...0
state(digest + 32, 32, SBUF(key)); // if this load fails then we don't care, the hash is just 0
nonce(digest + 64, 32); // todo: if we enforce sfFirstLedgerSequence = +1 then this will be impossible to cheat
uint8_t hash[32];
if (util_sha512h(SBUF(hash), SBUF(digest)) != 32)
rollback(SBUF("Doubler: Could not compute digest for coin flip."), 4);
if (state_set(SBUF(hash), SBUF(key)) != 32)
rollback(SBUF("Doubler: Could not set state."), 5);
// first digit of lcl hash is our biased coin flip, you lose 60% of the time :P
if (hash[0] % 10 < 6)
accept(SBUF("Doubler: Tails, you lose. Om nom nom xrp."), 4);
// before we start calling hook-api functions we should tell the hook how many tx we intend to create
etxn_reserve(1); // we are going to emit 1 transaction
// fetch the sent Amount
// Amounts can be 384 bits or 64 bits. If the Amount is an XRP value it will be 64 bits.
unsigned char amount_buffer[48];
int64_t amount_len = otxn_field(SBUF(amount_buffer), sfAmount);
int64_t drops_to_send = AMOUNT_TO_DROPS(amount_buffer) * 2; // doubler pays back 2x received
if (amount_len != 8)
rollback(SBUF("Doubler: Rejecting incoming non-XRP transaction"), 5);
int64_t fee_base = etxn_fee_base(PREPARE_PAYMENT_SIMPLE_SIZE);
uint8_t tx[PREPARE_PAYMENT_SIMPLE_SIZE];
// we will use an XRP payment macro, this will populate the buffer with a serialized binary transaction
// Parameter list: ( buf_out, drops_amount, drops_fee, to_address, dest_tag, src_tag )
PREPARE_PAYMENT_SIMPLE(tx, drops_to_send, fee_base, account_field, 0, 0);
// emit the transaction
uint8_t emithash[32];
emit(SBUF(emithash), SBUF(tx));
// accept and allow the original transaction through
accept(SBUF("Doubler: Heads, you won! Funds emitted!"), 0);
return 0;
}

43
hook-api-examples/doubler/install.js Normal file
View File

@@ -0,0 +1,43 @@
if (process.argv.length < 3)
{
console.log("Usage: node accept <account family seed>")
process.exit(1);
}
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
let wasm = t.findWasm();
if (wasm.length != 1)
{
console.log("There should be exactly one .wasm file in the current working directory.")
console.log("Try make")
process.exit(1);
}
const secret = process.argv[2];
const account = t.xrpljs.Wallet.fromSeed(secret)
t.api.submit(
{
Account: account.classicAddress,
TransactionType: "SetHook",
Hooks: [
{
Hook: {
CreateCode: t.wasm(wasm[0]),
HookApiVersion: 0,
HookNamespace: "CAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFECAFE",
HookOn: "0000000000000000",
Flags: t.hsfOVERRIDE
}
}
],
Fee: "100000"
}, {wallet: account}).then(x=>
{
t.assertTxnSuccess(x)
console.log(x);
process.exit(0);
}).catch(e=>console.log(e));
}).catch(e=>console.log(e));

3
hook-api-examples/doubler/makefile Normal file
View File

@@ -0,0 +1,3 @@
all:
wasmcc doubler.c -o doubler.wasm -O0 -Wl,--allow-undefined -I../

19
hook-api-examples/doubler/pay.js Normal file
View File

@@ -0,0 +1,19 @@
if (process.argv.length < 5)
{
console.log("Usage: node pay <source family seed> <amount xrp> <destination account>")
process.exit(1)
}
const secret = process.argv[2];
const amount = BigInt(process.argv[3]) * 1000000n
const dest = process.argv[4];
require('../utils-tests.js').TestRig('ws://localhost:6005').then(t=>
{
t.pay(secret, amount, dest).then(x=>
{
console.log(x);
process.exit(0);
});
});

27
hook-api-examples/generate_sfcodes.sh Executable file
View File

@@ -0,0 +1,27 @@
#/bin/bash
RIPPLED_SRC_DIR=../src/
echo '/**
* This file contains programmatically generated sf field codes
*/'
cat $RIPPLED_SRC_DIR/ripple/protocol/impl/SField.cpp | grep -E '^CONSTRUCT_' |
sed 's/UINT16/1/g' |
sed 's/UINT32/2/g' |
sed 's/UINT64/3/g' |
sed 's/HASH128/4/g' |
sed 's/HASH256/5/g' |
sed 's/AMOUNT/6/g' |
sed 's/VL/7/g' |
sed 's/ACCOUNT/8/g' |
sed 's/OBJECT/14/g' |
sed 's/ARRAY/15/g' |
sed 's/UINT8/16/g' |
sed 's/HASH160/17/g' |
sed 's/PATHSET/18/g' |
sed 's/VECTOR256/19/g' |
sed 's/UINT96/20/g' |
sed 's/UINT192/21/g' |
sed 's/UINT384/22/g' |
sed 's/UINT512/23/g' |
grep -Eo '"([^"]+)", *([0-9]+), *([0-9]+)' |
sed 's/"//g' | sed 's/ *//g' | sed 's/,/ /g' |
awk '{print ("#define sf"$1" (("$2"U << 16U) + "$3"U)")}'

417
hook-api-examples/hookapi.h Normal file
View File

@@ -0,0 +1,417 @@
/**
* Hook API include file
*
* Note to the reader:
* This include defines two types of things: external functions and macros
* Functions are used sparingly because a non-inlining compiler may produce
* undesirable output.
*
* Find documentation here: https://xrpl-hooks.readme.io/reference/
*/
#ifndef HOOKAPI_INCLUDED
#define HOOKAPI_INCLUDED 1
#include <stdint.h>
//int64_t hook(uint32_t reserved) __attribute__((used));
//int64_t cbak(uint32_t reserved) __attribute__((used));
/**
* Guard function. Each time a loop appears in your code a call to this must be the first branch instruction after the
* beginning of the loop.
* @param id The identifier of the guard (typically the line number).
* @param maxiter The maximum number of times this loop will iterate across the life of the hook.
* @return Can be ignored. If the guard is violated the hook will terminate.
*/
extern int32_t _g (uint32_t id, uint32_t maxiter);
/**
* Accept the originating transaction and commit all hook state changes and submit all emitted transactions.
* @param read_ptr An optional string to use as a return comment. May be 0.
* @param read_len The length of the string. May be 0.
* @return Will never return, terminates the hook.
*/
extern int64_t accept (uint32_t read_ptr, uint32_t read_len, int64_t error_code);
/**
* Rollback the originating transaction, discard all hook state changes and emitted transactions.
* @param read_ptr An optional string to use as a return comment. May be 0.
* @param read_len The length of the string. May be 0.
* @return Will never return, terminates the hook.
*/
extern int64_t rollback (uint32_t read_ptr, uint32_t read_len, int64_t error_code);
/**
* Read a 20 byte account-id from the memory pointed to by read_ptr of length read_len and encode it to a base58-check
* encoded r-address.
* @param read_ptr The memory address of the account-id
* @param read_len The byte length of the account-id (should always be 20)
* @param write_ptr The memory address of a suitable buffer to write the encoded r-address into.
* @param write_len The size of the write buffer.
* @return On success the length of the r-address will be returned indicating the bytes written to the write buffer.
* On failure a negative integer is returned indicating what went wrong.
*/
extern int64_t util_raddr (uint32_t write_ptr, uint32_t write_len,
uint32_t read_ptr, uint32_t read_len);
/**
* Read an r-address from the memory pointed to by read_ptr of length read_len and decode it to a 20 byte account id
* and write to write_ptr
* @param read_ptr The memory address of the r-address
* @param read_len The byte length of the r-address
* @param write_ptr The memory address of a suitable buffer to write the decoded account id into.
* @param write_len The size of the write buffer.
* @return On success 20 will be returned indicating the bytes written. On failure a negative integer is returned
* indicating what went wrong.
*/
extern int64_t util_accid (uint32_t write_ptr, uint32_t write_len,
uint32_t read_ptr, uint32_t read_len);
/**
* Verify a cryptographic signature either ED25519 of SECP256k1. Public key should be prefixed with 0xED for 25519.
* @param dread_ptr The memory location of the data or payload to verify
* @param dread_len The length of the data or payload to verify
* @param sread_ptr The memory location of the signature
* @param sread_len The length of the signature
* @param kread_ptr The memory location of the public key
* @param kread_len The length of the public key
* @return True if and only if the signature was verified.
*/
extern int64_t util_verify (uint32_t dread_ptr, uint32_t dread_len,
uint32_t sread_ptr, uint32_t sread_len,
uint32_t kread_ptr, uint32_t kread_len);
/**
* Compute the first half of a SHA512 checksum.
* @param write_ptr The buffer to write the checksum into. Must be at least 32 bytes.
* @param write_len The length of the buffer.
* @param read_ptr The buffer to read data for digest from.
* @param read_len The amount of data to read from the buffer.
* @return The number of bytes written to write_ptr or a negative integer on error.
*/
extern int64_t util_sha512h (uint32_t write_ptr, uint32_t write_len,
uint32_t read_ptr, uint32_t read_len);
/**
* Index into a xrpld serialized object and return the location and length of a subfield. Except for Array subtypes
* the offset and length refer to the **payload** of the subfield not the entire subfield. Use SUB_OFFSET and
* SUB_LENGTH macros to extract return value.
* @param read_ptr The memory location of the stobject
* @param read_len The length of the stobject
* @param field_id The Field Code of the subfield
* @return high-word (most significant 4 bytes excluding the most significant bit (MSB)) is the field offset relative
* to read_ptr and the low-word (least significant 4 bytes) is its length. MSB is sign bit, if set (negative)
* return value indicates error (typically error means could not find.)
*/
extern int64_t sto_subfield (uint32_t read_ptr, uint32_t read_len, uint32_t field_id );
/**
* Index into a xrpld serialized array and return the location and length of an index. Unlike sto_subfield this api
* always returns the offset and length of the whole object at that index (not its payload.) Use SUB_OFFSET and
* SUB_LENGTH macros to extract return value.
* @param read_ptr The memory location of the stobject
* @param read_len The length of the stobject
* @param array_id The index requested
* @return high-word (most significant 4 bytes excluding the most significant bit (MSB)) is the field offset relative
* to read_ptr and the low-word (least significant 4 bytes) is its length. MSB is sign bit, if set (negative)
* return value indicates error (typically error means could not find.)
*/
extern int64_t sto_subarray (uint32_t read_ptr, uint32_t read_len, uint32_t array_id);
extern int64_t sto_validate (uint32_t read_ptr, uint32_t read_len);
extern int64_t sto_emplace (uint32_t write_ptr, uint32_t write_len,
uint32_t sread_ptr, uint32_t sread_len,
uint32_t fread_ptr, uint32_t fread_len, uint32_t field_id);
extern int64_t sto_erase (uint32_t write_ptr, uint32_t write_len,
uint32_t read_ptr, uint32_t read_len, uint32_t field_id);
extern int64_t util_keylet (uint32_t write_ptr, uint32_t write_len, uint32_t keylet_type,
uint32_t a, uint32_t b, uint32_t c,
uint32_t d, uint32_t e, uint32_t f);
/**
* Compute burden for an emitted transaction.
* @return the burden a theoretically emitted transaction would have.
*/
extern int64_t etxn_burden (void );
/**
* Write a full emit_details stobject into the buffer specified.
* @param write_ptr A sufficiently large buffer to write into.
* @param write_len The length of that buffer.
* @return The number of bytes written or a negative integer indicating an error.
*/
extern int64_t etxn_details (uint32_t write_ptr, uint32_t write_len);
/**
* Compute the minimum fee required to be paid by a hypothetically emitted transaction based on its size in bytes.
* @param The size of the emitted transaction in bytes
* @return The minimum fee in drops this transaction should pay to succeed
*/
extern int64_t etxn_fee_base (uint32_t tx_byte_count);
/**
* Inform xrpld that you will be emitting at most @count@ transactions during the course of this hook execution.
* @param count The number of transactions you intend to emit from this hook.
* @return If a negaitve integer an error has occured
*/
extern int64_t etxn_reserve (uint32_t count);
/**
* Compute the generation of an emitted transaction. If this hook was invoked by a transaction emitted by a previous
* hook then the generation counter will be 1+ the previous generation counter otherwise it will be 1.
* @return The generation of a hypothetically emitted transaction.
*/
extern int64_t etxn_generation (void);
/**
* Emit a transaction from this hook.
* @param read_ptr Memory location of a buffer containing the fully formed binary transaction to emit.
* @param read_len The length of the transaction.
* @return A negative integer if the emission failed.
*/
extern int64_t emit (uint32_t write_ptr, uint32_t write_len, uint32_t read_ptr, uint32_t read_len);
/**
* Retrieve the account the hook is running on.
* @param write_ptr A buffer of at least 20 bytes to write into.
* @param write_len The length of that buffer
* @return The number of bytes written into the buffer of a negative integer if an error occured.
*/
extern int64_t hook_account (uint32_t write_ptr, uint32_t write_len);
/**
* Retrieve the hash of the currently executing hook.
* @param write_ptr A buffer of at least 32 bytes to write into.
* @param write_len The length of that buffer
* @return The number of bytes written into the buffer of a negative integer if an error occured.
*/
extern int64_t hook_hash (uint32_t write_ptr, uint32_t write_len);
/**
* Retrive the currently recommended minimum fee for a transaction to succeed.
*/
extern int64_t fee_base (void);
/**
* Retrieve the current ledger sequence number
*/
extern int64_t ledger_seq (void);
extern int64_t ledger_last_hash (uint32_t write_ptr, uint32_t write_len);
/**
* Retrieve a nonce for use in an emitted transaction (or another task). Can be called repeatedly for multiple nonces.
* @param write_ptr A buffer of at least 32 bytes to write into.
* @param write_len The length of that buffer
* @return The number of bytes written into the buffer of a negative integer if an error occured.
*/
extern int64_t nonce (uint32_t write_ptr, uint32_t write_len);
/**
* Slot functions have not been implemented yet and the api for them is subject to change
*/
extern int64_t slot (uint32_t write_ptr, uint32_t write_len, uint32_t slot);
extern int64_t slot_clear (uint32_t slot);
extern int64_t slot_count (uint32_t slot);
extern int64_t slot_id (uint32_t slot);
extern int64_t slot_set (uint32_t read_ptr, uint32_t read_len, int32_t slot);
extern int64_t slot_size (uint32_t slot);
extern int64_t slot_subarray (uint32_t parent_slot, uint32_t array_id, uint32_t new_slot);
extern int64_t slot_subfield (uint32_t parent_slot, uint32_t field_id, uint32_t new_slot);
extern int64_t slot_type (uint32_t slot, uint32_t flags);
extern int64_t slot_float (uint32_t slot);
extern int64_t trace_slot (uint32_t mread_ptr, uint32_t mread_len, uint32_t slot);
extern int64_t otxn_slot (uint32_t slot);
/**
* In the hook's state key-value map, set the value for the key pointed at by kread_ptr.
* @param read_ptr A buffer containing the data to store
* @param read_len The length of the data
* @param kread_ptr A buffer containing the key
* @param kread_len The length of the key
* @return The number of bytes stored or a negative integer if an error occured
*/
extern int64_t state_set (uint32_t read_ptr, uint32_t read_len,
uint32_t kread_ptr, uint32_t kread_len);
/**
* Retrieve a value from the hook's key-value map.
* @param write_ptr A buffer to write the state value into
* @param write_len The length of that buffer
* @param kread_ptr A buffer to read the state key from
* @param kread_len The length of that key
* @return The number of bytes written or a negative integer if an error occured.
*/
extern int64_t state (uint32_t write_ptr, uint32_t write_len,
uint32_t kread_ptr, uint32_t kread_len);
/**
* Retrieve a value from another hook's key-value map.
* @param write_ptr A buffer to write the state value into
* @param write_len The length of that buffer
* @param kread_ptr A buffer to read the state key from
* @param kread_len The length of that key
* @param aread_ptr A buffer containing an account-id of another account containing a hook whose state we are reading
* @param aread_len The length of the account-id (should always be 20).
* @return The number of bytes written or a negative integer if an error occured.
*/
extern int64_t state_foreign (uint32_t write_ptr, uint32_t write_len,
uint32_t kread_ptr, uint32_t kread_len,
uint32_t aread_ptr, uint32_t aread_len);
/**
* Print some output to the trace log on xrpld. Any xrpld instance set to "trace" log level will see this.
* @param read_ptr A buffer containing either data or text (in either utf8, or utf16le)
* @param read_len The byte length of the data/text to send to the trace log
* @param as_hex If 0 treat the read_ptr as pointing at a string of text, otherwise treat it as data and print hex
* @return The number of bytes output or a negative integer if an error occured.
*/
extern int64_t trace (uint32_t mread_ptr, uint32_t mread_len,
uint32_t dread_ptr, uint32_t dread_len, uint32_t as_hex);
/**
* Print some output to the trace log on xrpld along with a decimal number. Any xrpld instance set to "trace" log
* level will see this.
* @param read_ptr A pointer to the string to output
* @param read_len The length of the string to output
* @param number Any integer you wish to display after the text
* @return A negative value on error
*/
extern int64_t trace_num (uint32_t read_ptr, uint32_t read_len, int64_t number);
/**
* Retrieve the burden of the originating transaction (if any)
* @return The burden of the originating transaction
*/
extern int64_t otxn_burden (void);
/**
* Retrieve a field from the originating transaction as "full text" (The way it is displayed in JSON)
* @param write_ptr A buffer to write the representation into
* @param write_len The length of the buffer
* @param field_id The field code of the field being requested
* @return The number of bytes written to write_ptr or a negative integer if an error occured.
*/
extern int64_t otxn_field_txt (uint32_t write_ptr, uint32_t write_len, uint32_t field_id);
/**
* Retrieve a field from the originating transaction in its raw serialized form.
* @param write_ptr A buffer to output the field into
* @param write_len The length of the buffer.
* @param field_if The field code of the field being requested
* @return The number of bytes written to write_ptr or a negative integer if an error occured.
*/
extern int64_t otxn_field (uint32_t write_ptr, uint32_t write_len, uint32_t field_id);
/**
* Retrieve the generation of the originating transaction (if any).
* @return the generation of the originating transaction.
*/
extern int64_t otxn_generation (void);
/**
* Retrieve the TXNID of the originating transaction.
* @param write_ptr A buffer at least 32 bytes long
* @param write_len The length of the buffer.
* @return The number of bytes written into the buffer or a negative integer on failure.
*/
extern int64_t otxn_id (uint32_t write_ptr, uint32_t write_len);
/**
* Retrieve the Transaction Type (e.g. ttPayment = 0) of the originating transaction.
* @return The Transaction Type (tt-code)
*/
extern int64_t otxn_type (void);
extern int64_t float_set (int32_t exponent, int64_t mantissa );
extern int64_t float_multiply (int64_t float1, int64_t float2 );
extern int64_t float_mulratio (int64_t float1, uint32_t round_up,
uint32_t numerator, uint32_t denominator );
extern int64_t float_negate (int64_t float1 );
extern int64_t float_compare (int64_t float1, int64_t float2, uint32_t mode );
extern int64_t float_sum (int64_t float1, int64_t float2 );
extern int64_t float_sto (uint32_t write_ptr, uint32_t write_len,
uint32_t cread_ptr, uint32_t cread_len,
uint32_t iread_ptr, uint32_t iread_len,
int64_t float1, uint32_t field_code);
extern int64_t float_sto_set (uint32_t read_ptr, uint32_t read_len );
extern int64_t float_invert (int64_t float1 );
extern int64_t float_divide (int64_t float1, int64_t float2 );
extern int64_t float_one ();
extern int64_t float_exponent (int64_t float1 );
extern int64_t float_exponent_set (int64_t float1, int32_t exponent );
extern int64_t float_mantissa (int64_t float1 );
extern int64_t float_mantissa_set (int64_t float1, int64_t mantissa );
extern int64_t float_sign (int64_t float1 );
extern int64_t float_sign_set (int64_t float1, uint32_t negative );
extern int64_t float_int (int64_t float1, uint32_t decimal_places, uint32_t abs);
extern int64_t trace_float (uint32_t mread_ptr, uint32_t mread_len, int64_t float1);
#define SUCCESS 0 // return codes > 0 are reserved for hook apis to return "success"
#define OUT_OF_BOUNDS -1 // could not read or write to a pointer to provided by hook
#define INTERNAL_ERROR -2 // eg directory is corrupt
#define TOO_BIG -3 // something you tried to store was too big
#define TOO_SMALL -4 // something you tried to store or provide was too small
#define DOESNT_EXIST -5 // something you requested wasn't found
#define NO_FREE_SLOTS -6 // when trying to load an object there is a maximum of 255 slots
#define INVALID_ARGUMENT -7 // self explanatory
#define ALREADY_SET -8 // returned when a one-time parameter was already set by the hook
#define PREREQUISITE_NOT_MET -9 // returned if a required param wasn't set before calling
#define FEE_TOO_LARGE -10 // returned if the attempted operation would result in an absurd fee
#define EMISSION_FAILURE -11 // returned if an emitted tx was not accepted by rippled
#define TOO_MANY_NONCES -12 // a hook has a maximum of 256 nonces
#define TOO_MANY_EMITTED_TXN -13 // a hook has emitted more than its stated number of emitted txn
#define NOT_IMPLEMENTED -14 // an api was called that is reserved for a future version
#define INVALID_ACCOUNT -15 // an api expected an account id but got something else
#define GUARD_VIOLATION -16 // a guarded loop or function iterated over its maximum
#define INVALID_FIELD -17 // the field requested is returning sfInvalid
#define PARSE_ERROR -18 // hook asked hookapi to parse something the contents of which was invalid
#define RC_ROLLBACK -19 // used internally by hook api to indicate a rollback
#define RC_ACCEPT -20 // used internally by hook api to indicate an accept
#define NO_SUCH_KEYLET -21 // the specified keylet or keylet type does not exist or could not be computed
#define INVALID_FLOAT -10024 // if the mantissa or exponent are outside normalized ranges
#define KEYLET_HOOK 1
#define KEYLET_HOOK_STATE 2
#define KEYLET_ACCOUNT 3
#define KEYLET_AMENDMENTS 4
#define KEYLET_CHILD 5
#define KEYLET_SKIP 6
#define KEYLET_FEES 7
#define KEYLET_NEGATIVE_UNL 8
#define KEYLET_LINE 9
#define KEYLET_OFFER 10
#define KEYLET_QUALITY 11
#define KEYLET_EMITTED_DIR 12
#define KEYLET_TICKET 13
#define KEYLET_SIGNERS 14
#define KEYLET_CHECK 15
#define KEYLET_DEPOSIT_PREAUTH 16
#define KEYLET_UNCHECKED 17
#define KEYLET_OWNER_DIR 18
#define KEYLET_PAGE 19
#define KEYLET_ESCROW 20
#define KEYLET_PAYCHAN 21
#define KEYLET_EMITTED 22
#define COMPARE_EQUAL 1U
#define COMPARE_LESS 2U
#define COMPARE_GREATER 4U
#include "sfcodes.h"
#include "hookmacro.h"
#endif

536
hook-api-examples/hookmacro.h Normal file
View File

@@ -0,0 +1,536 @@
/**
* These are helper macros for writing hooks, all of them are optional as is including hookmacro.h at all
*/
#include <stdint.h>
#include "hookapi.h"
#include "sfcodes.h"
#ifndef HOOKMACROS_INCLUDED
#define HOOKMACROS_INCLUDED 1
// hook developers should use this guard macro, simply GUARD(<maximum iterations>)
#define GUARD(maxiter) _g(__LINE__, (maxiter)+1)
#define GUARDM(maxiter, n) _g(((__LINE__ << 16) + n), (maxiter)+1)
#define SBUF(str) (uint32_t)(str), sizeof(str)
#define REQUIRE(cond, str)\
{\
if (!(cond))\
rollback(SBUF(str), __LINE__);\
}
// make a report buffer as a c-string
// provide a name for a buffer to declare (buf)
// provide a static string
// provide an integer to print after the string
#define RBUF(buf, out_len, str, num)\
unsigned char buf[sizeof(str) + 21];\
int out_len = 0;\
{\
int i = 0;\
for (; GUARDM(sizeof(str),1),i < sizeof(str); ++i)\
(buf)[i] = str[i];\
if ((buf)[sizeof(str)-1] == 0) i--;\
if ((num) < 0) (buf)[i++] = '-';\
uint64_t unsigned_num = (uint64_t)( (num) < 0 ? (num) * -1 : (num) );\
uint64_t j = 10000000000000000000ULL;\
int start = 1;\
for (; GUARDM(20,2), unsigned_num > 0 && j > 0; j /= 10)\
{\
unsigned char digit = ( unsigned_num / j ) % 10;\
if (digit == 0 && start)\
continue;\
start = 0;\
(buf)[i++] = '0' + digit;\
}\
(buf)[i] = '\0';\
out_len = i;\
}
#define RBUF2(buff, out_len, str, num, str2, num2)\
unsigned char buff[sizeof(str) + sizeof(str2) + 42];\
int out_len = 0;\
{\
unsigned char* buf = buff;\
int i = 0;\
for (; GUARDM(sizeof(str),1),i < sizeof(str); ++i)\
(buf)[i] = str[i];\
if ((buf)[sizeof(str)-1] == 0) i--;\
if ((num) < 0) (buf)[i++] = '-';\
uint64_t unsigned_num = (uint64_t)( (num) < 0 ? (num) * -1 : (num) );\
uint64_t j = 10000000000000000000ULL;\
int start = 1;\
for (; GUARDM(20,2), unsigned_num > 0 && j > 0; j /= 10)\
{\
unsigned char digit = ( unsigned_num / j ) % 10;\
if (digit == 0 && start)\
continue;\
start = 0;\
(buf)[i++] = '0' + digit;\
}\
buf += i;\
out_len += i;\
i = 0;\
for (; GUARDM(sizeof(str2),3),i < sizeof(str2); ++i)\
(buf)[i] = str2[i];\
if ((buf)[sizeof(str2)-1] == 0) i--;\
if ((num2) < 0) (buf)[i++] = '-';\
unsigned_num = (uint64_t)( (num2) < 0 ? (num2) * -1 : (num2) );\
j = 10000000000000000000ULL;\
start = 1;\
for (; GUARDM(20,4), unsigned_num > 0 && j > 0; j /= 10)\
{\
unsigned char digit = ( unsigned_num / j ) % 10;\
if (digit == 0 && start)\
continue;\
start = 0;\
(buf)[i++] = '0' + digit;\
}\
(buf)[i] = '\0';\
out_len += i;\
}
#define TRACEVAR(v) trace_num((uint32_t)(#v), (uint32_t)(sizeof(#v)), (int64_t)v);
#define TRACEHEX(v) trace((uint32_t)(#v), (uint32_t)(sizeof(#v)), (uint32_t)(v), (uint32_t)(sizeof(v)), 1);
#define TRACEXFL(v) trace_float((uint32_t)(#v), (uint32_t)(sizeof(#v)), (int64_t)v);
#define TRACESTR(v) trace((uint32_t)(#v), (uint32_t)(sizeof(#v)), (uint32_t)(v), sizeof(v), 0);
#define CLEARBUF(b)\
{\
for (int x = 0; GUARD(sizeof(b)), x < sizeof(b); ++x)\
b[x] = 0;\
}
// returns an in64_t, negative if error, non-negative if valid drops
#define AMOUNT_TO_DROPS(amount_buffer)\
(((amount_buffer)[0] >> 7) ? -2 : (\
((((uint64_t)((amount_buffer)[0])) & 0xb00111111) << 56) +\
(((uint64_t)((amount_buffer)[1])) << 48) +\
(((uint64_t)((amount_buffer)[2])) << 40) +\
(((uint64_t)((amount_buffer)[3])) << 32) +\
(((uint64_t)((amount_buffer)[4])) << 24) +\
(((uint64_t)((amount_buffer)[5])) << 16) +\
(((uint64_t)((amount_buffer)[6])) << 8) +\
(((uint64_t)((amount_buffer)[7])))))
#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
// when using this macro buf1len may be dynamic but buf2len must be static
// provide n >= 1 to indicate how many times the macro will be hit on the line of code
// e.g. if it is in a loop that loops 10 times n = 10
#define BUFFER_EQUAL_GUARD(output, buf1, buf1len, buf2, buf2len, n)\
{\
output = ((buf1len) == (buf2len) ? 1 : 0);\
for (int x = 0; GUARDM( (buf2len) * (n), 1 ), x < (buf2len);\
++x)\
{\
if ((buf1)[x] != (buf2)[x])\
{\
output = 0;\
break;\
}\
}\
}
#define BUFFER_SWAP(x,y)\
{\
uint8_t* z = x;\
x = y;\
y = z;\
}
#define ACCOUNT_COMPARE(compare_result, buf1, buf2)\
{\
compare_result = 0;\
for (int i = 0; GUARD(20), i < 20; ++i)\
{\
if (buf1[i] > buf2[i])\
{\
compare_result = 1;\
break;\
}\
else if (buf1[i] < buf2[i])\
{\
compare_result = -1;\
break;\
}\
}\
}
#define BUFFER_EQUAL_STR_GUARD(output, buf1, buf1len, str, n)\
BUFFER_EQUAL_GUARD(output, buf1, buf1len, str, (sizeof(str)-1), n)
#define BUFFER_EQUAL_STR(output, buf1, buf1len, str)\
BUFFER_EQUAL_GUARD(output, buf1, buf1len, str, (sizeof(str)-1), 1)
#define BUFFER_EQUAL(output, buf1, buf2, compare_len)\
BUFFER_EQUAL_GUARD(output, buf1, compare_len, buf2, compare_len, 1)
#define UINT16_TO_BUF(buf_raw, i)\
{\
unsigned char* buf = (unsigned char*)buf_raw;\
buf[0] = (((uint64_t)i) >> 8) & 0xFFUL;\
buf[1] = (((uint64_t)i) >> 0) & 0xFFUL;\
}
#define UINT16_FROM_BUF(buf)\
(((uint64_t)((buf)[0]) << 8) +\
((uint64_t)((buf)[1]) << 0))
#define UINT32_TO_BUF(buf_raw, i)\
{\
unsigned char* buf = (unsigned char*)buf_raw;\
buf[0] = (((uint64_t)i) >> 24) & 0xFFUL;\
buf[1] = (((uint64_t)i) >> 16) & 0xFFUL;\
buf[2] = (((uint64_t)i) >> 8) & 0xFFUL;\
buf[3] = (((uint64_t)i) >> 0) & 0xFFUL;\
}
#define UINT32_FROM_BUF(buf)\
(((uint64_t)((buf)[0]) << 24) +\
((uint64_t)((buf)[1]) << 16) +\
((uint64_t)((buf)[2]) << 8) +\
((uint64_t)((buf)[3]) << 0))
#define UINT64_TO_BUF(buf_raw, i)\
{\
unsigned char* buf = (unsigned char*)buf_raw;\
buf[0] = (((uint64_t)i) >> 56) & 0xFFUL;\
buf[1] = (((uint64_t)i) >> 48) & 0xFFUL;\
buf[2] = (((uint64_t)i) >> 40) & 0xFFUL;\
buf[3] = (((uint64_t)i) >> 32) & 0xFFUL;\
buf[4] = (((uint64_t)i) >> 24) & 0xFFUL;\
buf[5] = (((uint64_t)i) >> 16) & 0xFFUL;\
buf[6] = (((uint64_t)i) >> 8) & 0xFFUL;\
buf[7] = (((uint64_t)i) >> 0) & 0xFFUL;\
}
#define UINT64_FROM_BUF(buf)\
(((uint64_t)((buf)[0]) << 56) +\
((uint64_t)((buf)[1]) << 48) +\
((uint64_t)((buf)[2]) << 40) +\
((uint64_t)((buf)[3]) << 32) +\
((uint64_t)((buf)[4]) << 24) +\
((uint64_t)((buf)[5]) << 16) +\
((uint64_t)((buf)[6]) << 8) +\
((uint64_t)((buf)[7]) << 0))
#define INT64_FROM_BUF(buf)\
((((uint64_t)((buf)[0]&7FU) << 56) +\
((uint64_t)((buf)[1]) << 48) +\
((uint64_t)((buf)[2]) << 40) +\
((uint64_t)((buf)[3]) << 32) +\
((uint64_t)((buf)[4]) << 24) +\
((uint64_t)((buf)[5]) << 16) +\
((uint64_t)((buf)[6]) << 8) +\
((uint64_t)((buf)[7]) << 0)) * (buf[0] & 0x80U ? -1 : 1))
#define INT64_TO_BUF(buf_raw, i)\
{\
unsigned char* buf = (unsigned char*)buf_raw;\
buf[0] = (((uint64_t)i) >> 56) & 0x7FUL;\
buf[1] = (((uint64_t)i) >> 48) & 0xFFUL;\
buf[2] = (((uint64_t)i) >> 40) & 0xFFUL;\
buf[3] = (((uint64_t)i) >> 32) & 0xFFUL;\
buf[4] = (((uint64_t)i) >> 24) & 0xFFUL;\
buf[5] = (((uint64_t)i) >> 16) & 0xFFUL;\
buf[6] = (((uint64_t)i) >> 8) & 0xFFUL;\
buf[7] = (((uint64_t)i) >> 0) & 0xFFUL;\
if (i < 0) buf[0] |= 0x80U;\
}
#define ttPAYMENT 0
#define tfCANONICAL 0x80000000UL
#define atACCOUNT 1U
#define atOWNER 2U
#define atDESTINATION 3U
#define atISSUER 4U
#define atAUTHORIZE 5U
#define atUNAUTHORIZE 6U
#define atTARGET 7U
#define atREGULARKEY 8U
#define atPSEUDOCALLBACK 9U
#define amAMOUNT 1U
#define amBALANCE 2U
#define amLIMITAMOUNT 3U
#define amTAKERPAYS 4U
#define amTAKERGETS 5U
#define amLOWLIMIT 6U
#define amHIGHLIMIT 7U
#define amFEE 8U
#define amSENDMAX 9U
#define amDELIVERMIN 10U
#define amMINIMUMOFFER 16U
#define amRIPPLEESCROW 17U
#define amDELIVEREDAMOUNT 18U
/**
* RH NOTE -- PAY ATTENTION
*
* ALL 'ENCODE' MACROS INCREMENT BUF_OUT
* THIS IS TO MAKE CHAINING EASY
* BUF_OUT IS A SACRIFICIAL POINTER
*
* 'ENCODE' MACROS WITH CONSTANTS HAVE
* ALIASING TO ASSIST YOU WITH ORDER
* _TYPECODE_FIELDCODE_ENCODE_MACRO
* TO PRODUCE A SERIALIZED OBJECT
* IN CANONICAL FORMAT YOU MUST ORDER
* FIRST BY TYPE CODE THEN BY FIELD CODE
*
* ALL 'PREPARE' MACROS PRESERVE POINTERS
*
**/
#define ENCODE_TL_SIZE 49
#define ENCODE_TL(buf_out, tlamt, amount_type)\
{\
uint8_t uat = amount_type; \
buf_out[0] = 0x60U +(uat & 0x0FU ); \
for (int i = 1; GUARDM(48, 1), i < 49; ++i)\
buf_out[i] = tlamt[i-1];\
buf_out += ENCODE_TL_SIZE;\
}
#define _06_XX_ENCODE_TL(buf_out, drops, amount_type )\
ENCODE_TL(buf_out, drops, amount_type );
#define ENCODE_TL_AMOUNT(buf_out, drops )\
ENCODE_TL(buf_out, drops, amAMOUNT );
#define _06_01_ENCODE_TL_AMOUNT(buf_out, drops )\
ENCODE_TL_AMOUNT(buf_out, drops );
// Encode drops to serialization format
// consumes 9 bytes
#define ENCODE_DROPS_SIZE 9
#define ENCODE_DROPS(buf_out, drops, amount_type ) \
{\
uint8_t uat = amount_type; \
uint64_t udrops = drops; \
buf_out[0] = 0x60U +(uat & 0x0FU ); \
buf_out[1] = 0b01000000 + (( udrops >> 56 ) & 0b00111111 ); \
buf_out[2] = (udrops >> 48) & 0xFFU; \
buf_out[3] = (udrops >> 40) & 0xFFU; \
buf_out[4] = (udrops >> 32) & 0xFFU; \
buf_out[5] = (udrops >> 24) & 0xFFU; \
buf_out[6] = (udrops >> 16) & 0xFFU; \
buf_out[7] = (udrops >> 8) & 0xFFU; \
buf_out[8] = (udrops >> 0) & 0xFFU; \
buf_out += ENCODE_DROPS_SIZE; \
}
#define _06_XX_ENCODE_DROPS(buf_out, drops, amount_type )\
ENCODE_DROPS(buf_out, drops, amount_type );
#define ENCODE_DROPS_AMOUNT(buf_out, drops )\
ENCODE_DROPS(buf_out, drops, amAMOUNT );
#define _06_01_ENCODE_DROPS_AMOUNT(buf_out, drops )\
ENCODE_DROPS_AMOUNT(buf_out, drops );
#define ENCODE_DROPS_FEE(buf_out, drops )\
ENCODE_DROPS(buf_out, drops, amFEE );
#define _06_08_ENCODE_DROPS_FEE(buf_out, drops )\
ENCODE_DROPS_FEE(buf_out, drops );
#define ENCODE_TT_SIZE 3
#define ENCODE_TT(buf_out, tt )\
{\
uint8_t utt = tt;\
buf_out[0] = 0x12U;\
buf_out[1] =(utt >> 8 ) & 0xFFU;\
buf_out[2] =(utt >> 0 ) & 0xFFU;\
buf_out += ENCODE_TT_SIZE; \
}
#define _01_02_ENCODE_TT(buf_out, tt)\
ENCODE_TT(buf_out, tt);
#define ENCODE_ACCOUNT_SIZE 22
#define ENCODE_ACCOUNT(buf_out, account_id, account_type)\
{\
uint8_t uat = account_type;\
buf_out[0] = 0x80U + uat;\
buf_out[1] = 0x14U;\
*(uint64_t*)(buf_out + 2) = *(uint64_t*)(account_id + 0);\
*(uint64_t*)(buf_out + 10) = *(uint64_t*)(account_id + 8);\
*(uint32_t*)(buf_out + 18) = *(uint32_t*)(account_id + 16);\
buf_out += ENCODE_ACCOUNT_SIZE;\
}
#define _08_XX_ENCODE_ACCOUNT(buf_out, account_id, account_type)\
ENCODE_ACCOUNT(buf_out, account_id, account_type);
#define ENCODE_ACCOUNT_SRC_SIZE 22
#define ENCODE_ACCOUNT_SRC(buf_out, account_id)\
ENCODE_ACCOUNT(buf_out, account_id, atACCOUNT);
#define _08_01_ENCODE_ACCOUNT_SRC(buf_out, account_id)\
ENCODE_ACCOUNT_SRC(buf_out, account_id);
#define ENCODE_ACCOUNT_DST_SIZE 22
#define ENCODE_ACCOUNT_DST(buf_out, account_id)\
ENCODE_ACCOUNT(buf_out, account_id, atDESTINATION);
#define _08_03_ENCODE_ACCOUNT_DST(buf_out, account_id)\
ENCODE_ACCOUNT_DST(buf_out, account_id);
#define ENCODE_UINT32_COMMON_SIZE 5U
#define ENCODE_UINT32_COMMON(buf_out, i, field)\
{\
uint32_t ui = i; \
uint8_t uf = field; \
buf_out[0] = 0x20U +(uf & 0x0FU); \
buf_out[1] =(ui >> 24 ) & 0xFFU; \
buf_out[2] =(ui >> 16 ) & 0xFFU; \
buf_out[3] =(ui >> 8 ) & 0xFFU; \
buf_out[4] =(ui >> 0 ) & 0xFFU; \
buf_out += ENCODE_UINT32_COMMON_SIZE; \
}
#define _02_XX_ENCODE_UINT32_COMMON(buf_out, i, field)\
ENCODE_UINT32_COMMON(buf_out, i, field)\
#define ENCODE_UINT32_UNCOMMON_SIZE 6U
#define ENCODE_UINT32_UNCOMMON(buf_out, i, field)\
{\
uint32_t ui = i; \
uint8_t uf = field; \
buf_out[0] = 0x20U; \
buf_out[1] = uf; \
buf_out[2] =(ui >> 24 ) & 0xFFU; \
buf_out[3] =(ui >> 16 ) & 0xFFU; \
buf_out[4] =(ui >> 8 ) & 0xFFU; \
buf_out[5] =(ui >> 0 ) & 0xFFU; \
buf_out += ENCODE_UINT32_UNCOMMON_SIZE; \
}
#define _02_XX_ENCODE_UINT32_UNCOMMON(buf_out, i, field)\
ENCODE_UINT32_UNCOMMON(buf_out, i, field)\
#define ENCODE_LLS_SIZE 6U
#define ENCODE_LLS(buf_out, lls )\
ENCODE_UINT32_UNCOMMON(buf_out, lls, 0x1B );
#define _02_27_ENCODE_LLS(buf_out, lls )\
ENCODE_LLS(buf_out, lls );
#define ENCODE_FLS_SIZE 6U
#define ENCODE_FLS(buf_out, fls )\
ENCODE_UINT32_UNCOMMON(buf_out, fls, 0x1A );
#define _02_26_ENCODE_FLS(buf_out, fls )\
ENCODE_FLS(buf_out, fls );
#define ENCODE_TAG_SRC_SIZE 5
#define ENCODE_TAG_SRC(buf_out, tag )\
ENCODE_UINT32_COMMON(buf_out, tag, 0x3U );
#define _02_03_ENCODE_TAG_SRC(buf_out, tag )\
ENCODE_TAG_SRC(buf_out, tag );
#define ENCODE_TAG_DST_SIZE 5
#define ENCODE_TAG_DST(buf_out, tag )\
ENCODE_UINT32_COMMON(buf_out, tag, 0xEU );
#define _02_14_ENCODE_TAG_DST(buf_out, tag )\
ENCODE_TAG_DST(buf_out, tag );
#define ENCODE_SEQUENCE_SIZE 5
#define ENCODE_SEQUENCE(buf_out, sequence )\
ENCODE_UINT32_COMMON(buf_out, sequence, 0x4U );
#define _02_04_ENCODE_SEQUENCE(buf_out, sequence )\
ENCODE_SEQUENCE(buf_out, sequence );
#define ENCODE_FLAGS_SIZE 5
#define ENCODE_FLAGS(buf_out, tag )\
ENCODE_UINT32_COMMON(buf_out, tag, 0x2U );
#define _02_02_ENCODE_FLAGS(buf_out, tag )\
ENCODE_FLAGS(buf_out, tag );
#define ENCODE_SIGNING_PUBKEY_SIZE 35
#define ENCODE_SIGNING_PUBKEY(buf_out, pkey )\
{\
buf_out[0] = 0x73U;\
buf_out[1] = 0x21U;\
*(uint64_t*)(buf_out + 2) = *(uint64_t*)(pkey + 0);\
*(uint64_t*)(buf_out + 10) = *(uint64_t*)(pkey + 8);\
*(uint64_t*)(buf_out + 18) = *(uint64_t*)(pkey + 16);\
*(uint64_t*)(buf_out + 26) = *(uint64_t*)(pkey + 24);\
buf[34] = pkey[32];\
buf_out += ENCODE_SIGNING_PUBKEY_SIZE;\
}
#define _07_03_ENCODE_SIGNING_PUBKEY(buf_out, pkey )\
ENCODE_SIGNING_PUBKEY(buf_out, pkey );
#define ENCODE_SIGNING_PUBKEY_NULL_SIZE 35
#define ENCODE_SIGNING_PUBKEY_NULL(buf_out )\
{\
buf_out[0] = 0x73U;\
buf_out[1] = 0x21U;\
*(uint64_t*)(buf_out+2) = 0;\
*(uint64_t*)(buf_out+10) = 0;\
*(uint64_t*)(buf_out+18) = 0;\
*(uint64_t*)(buf_out+25) = 0;\
buf_out += ENCODE_SIGNING_PUBKEY_NULL_SIZE;\
}
#define _07_03_ENCODE_SIGNING_PUBKEY_NULL(buf_out )\
ENCODE_SIGNING_PUBKEY_NULL(buf_out );
#define PREPARE_PAYMENT_SIMPLE_SIZE 270
#define PREPARE_PAYMENT_SIMPLE(buf_out_master, drops_amount_raw, drops_fee_raw, to_address, dest_tag_raw, src_tag_raw)\
{\
uint8_t* buf_out = buf_out_master;\
uint8_t acc[20];\
uint64_t drops_amount = (drops_amount_raw);\
uint64_t drops_fee = (drops_fee_raw);\
uint32_t dest_tag = (dest_tag_raw);\
uint32_t src_tag = (src_tag_raw);\
uint32_t cls = (uint32_t)ledger_seq();\
hook_account(SBUF(acc));\
_01_02_ENCODE_TT (buf_out, ttPAYMENT ); /* uint16 | size 3 */ \
_02_02_ENCODE_FLAGS (buf_out, tfCANONICAL ); /* uint32 | size 5 */ \
_02_03_ENCODE_TAG_SRC (buf_out, src_tag ); /* uint32 | size 5 */ \
_02_04_ENCODE_SEQUENCE (buf_out, 0 ); /* uint32 | size 5 */ \
_02_14_ENCODE_TAG_DST (buf_out, dest_tag ); /* uint32 | size 5 */ \
_02_26_ENCODE_FLS (buf_out, cls + 1 ); /* uint32 | size 6 */ \
_02_27_ENCODE_LLS (buf_out, cls + 5 ); /* uint32 | size 6 */ \
_06_01_ENCODE_DROPS_AMOUNT (buf_out, drops_amount ); /* amount | size 9 */ \
_06_08_ENCODE_DROPS_FEE (buf_out, drops_fee ); /* amount | size 9 */ \
_07_03_ENCODE_SIGNING_PUBKEY_NULL (buf_out ); /* pk | size 35 */ \
_08_01_ENCODE_ACCOUNT_SRC (buf_out, acc ); /* account | size 22 */ \
_08_03_ENCODE_ACCOUNT_DST (buf_out, to_address ); /* account | size 22 */ \
etxn_details((uint32_t)buf_out, 138); /* emitdet | size 138 */ \
}
#define PREPARE_PAYMENT_SIMPLE_TRUSTLINE_SIZE 309
#define PREPARE_PAYMENT_SIMPLE_TRUSTLINE(buf_out_master, tlamt, drops_fee_raw, to_address, dest_tag_raw, src_tag_raw)\
{\
uint8_t* buf_out = buf_out_master;\
uint8_t acc[20];\
uint64_t drops_fee = (drops_fee_raw);\
uint32_t dest_tag = (dest_tag_raw);\
uint32_t src_tag = (src_tag_raw);\
uint32_t cls = (uint32_t)ledger_seq();\
hook_account(SBUF(acc));\
_01_02_ENCODE_TT (buf_out, ttPAYMENT ); /* uint16 | size 3 */ \
_02_02_ENCODE_FLAGS (buf_out, tfCANONICAL ); /* uint32 | size 5 */ \
_02_03_ENCODE_TAG_SRC (buf_out, src_tag ); /* uint32 | size 5 */ \
_02_04_ENCODE_SEQUENCE (buf_out, 0 ); /* uint32 | size 5 */ \
_02_14_ENCODE_TAG_DST (buf_out, dest_tag ); /* uint32 | size 5 */ \
_02_26_ENCODE_FLS (buf_out, cls + 1 ); /* uint32 | size 6 */ \
_02_27_ENCODE_LLS (buf_out, cls + 5 ); /* uint32 | size 6 */ \
_06_01_ENCODE_TL_AMOUNT (buf_out, tlamt ); /* amount | size 48 */ \
_06_08_ENCODE_DROPS_FEE (buf_out, drops_fee ); /* amount | size 9 */ \
_07_03_ENCODE_SIGNING_PUBKEY_NULL (buf_out ); /* pk | size 35 */ \
_08_01_ENCODE_ACCOUNT_SRC (buf_out, acc ); /* account | size 22 */ \
_08_03_ENCODE_ACCOUNT_DST (buf_out, to_address ); /* account | size 22 */ \
etxn_details((uint32_t)buf_out, 138); /* emitdet | size 138 */ \
}
#endif

15
hook-api-examples/package.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "hook-api-examples",
"version": "1.0.0",
"description": "",
"main": "''",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC",
"dependencies": {
"ripple-keypairs": "^1.1.3",
"xrpl-hooks": "^2.1.1"
}
}

202
hook-api-examples/sfcodes.h Normal file
View File

@@ -0,0 +1,202 @@
/**
* This file contains programmatically generated sf field codes
*/
#define sfCloseResolution ((16U << 16U) + 1U)
#define sfMethod ((16U << 16U) + 2U)
#define sfTransactionResult ((16U << 16U) + 3U)
#define sfTickSize ((16U << 16U) + 16U)
#define sfUNLModifyDisabling ((16U << 16U) + 17U)
#define sfHookResult ((16U << 16U) + 18U)
#define sfLedgerEntryType ((1U << 16U) + 1U)
#define sfTransactionType ((1U << 16U) + 2U)
#define sfSignerWeight ((1U << 16U) + 3U)
#define sfTransferFee ((1U << 16U) + 4U)
#define sfVersion ((1U << 16U) + 16U)
#define sfHookStateChangeCount ((1U << 16U) + 17U)
#define sfHookEmitCount ((1U << 16U) + 18U)
#define sfHookExecutionIndex ((1U << 16U) + 19U)
#define sfHookApiVersion ((1U << 16U) + 20U)
#define sfFlags ((2U << 16U) + 2U)
#define sfSourceTag ((2U << 16U) + 3U)
#define sfSequence ((2U << 16U) + 4U)
#define sfPreviousTxnLgrSeq ((2U << 16U) + 5U)
#define sfLedgerSequence ((2U << 16U) + 6U)
#define sfCloseTime ((2U << 16U) + 7U)
#define sfParentCloseTime ((2U << 16U) + 8U)
#define sfSigningTime ((2U << 16U) + 9U)
#define sfExpiration ((2U << 16U) + 10U)
#define sfTransferRate ((2U << 16U) + 11U)
#define sfWalletSize ((2U << 16U) + 12U)
#define sfOwnerCount ((2U << 16U) + 13U)
#define sfDestinationTag ((2U << 16U) + 14U)
#define sfHighQualityIn ((2U << 16U) + 16U)
#define sfHighQualityOut ((2U << 16U) + 17U)
#define sfLowQualityIn ((2U << 16U) + 18U)
#define sfLowQualityOut ((2U << 16U) + 19U)
#define sfQualityIn ((2U << 16U) + 20U)
#define sfQualityOut ((2U << 16U) + 21U)
#define sfStampEscrow ((2U << 16U) + 22U)
#define sfBondAmount ((2U << 16U) + 23U)
#define sfLoadFee ((2U << 16U) + 24U)
#define sfOfferSequence ((2U << 16U) + 25U)
#define sfFirstLedgerSequence ((2U << 16U) + 26U)
#define sfLastLedgerSequence ((2U << 16U) + 27U)
#define sfTransactionIndex ((2U << 16U) + 28U)
#define sfOperationLimit ((2U << 16U) + 29U)
#define sfReferenceFeeUnits ((2U << 16U) + 30U)
#define sfReserveBase ((2U << 16U) + 31U)
#define sfReserveIncrement ((2U << 16U) + 32U)
#define sfSetFlag ((2U << 16U) + 33U)
#define sfClearFlag ((2U << 16U) + 34U)
#define sfSignerQuorum ((2U << 16U) + 35U)
#define sfCancelAfter ((2U << 16U) + 36U)
#define sfFinishAfter ((2U << 16U) + 37U)
#define sfSignerListID ((2U << 16U) + 38U)
#define sfSettleDelay ((2U << 16U) + 39U)
#define sfTicketCount ((2U << 16U) + 40U)
#define sfTicketSequence ((2U << 16U) + 41U)
#define sfTokenTaxon ((2U << 16U) + 42U)
#define sfMintedTokens ((2U << 16U) + 43U)
#define sfBurnedTokens ((2U << 16U) + 44U)
#define sfHookStateCount ((2U << 16U) + 45U)
#define sfEmitGeneration ((2U << 16U) + 46U)
#define sfIndexNext ((3U << 16U) + 1U)
#define sfIndexPrevious ((3U << 16U) + 2U)
#define sfBookNode ((3U << 16U) + 3U)
#define sfOwnerNode ((3U << 16U) + 4U)
#define sfBaseFee ((3U << 16U) + 5U)
#define sfExchangeRate ((3U << 16U) + 6U)
#define sfLowNode ((3U << 16U) + 7U)
#define sfHighNode ((3U << 16U) + 8U)
#define sfDestinationNode ((3U << 16U) + 9U)
#define sfCookie ((3U << 16U) + 10U)
#define sfServerVersion ((3U << 16U) + 11U)
#define sfOfferNode ((3U << 16U) + 12U)
#define sfEmitBurden ((3U << 16U) + 13U)
#define sfHookOn ((3U << 16U) + 16U)
#define sfHookInstructionCount ((3U << 16U) + 17U)
#define sfHookReturnCode ((3U << 16U) + 18U)
#define sfReferenceCount ((3U << 16U) + 19U)
#define sfEmailHash ((4U << 16U) + 1U)
#define sfTakerPaysCurrency ((17U << 16U) + 1U)
#define sfTakerPaysIssuer ((17U << 16U) + 2U)
#define sfTakerGetsCurrency ((17U << 16U) + 3U)
#define sfTakerGetsIssuer ((17U << 16U) + 4U)
#define sfLedgerHash ((5U << 16U) + 1U)
#define sfParentHash ((5U << 16U) + 2U)
#define sfTransactionHash ((5U << 16U) + 3U)
#define sfAccountHash ((5U << 16U) + 4U)
#define sfPreviousTxnID ((5U << 16U) + 5U)
#define sfLedgerIndex ((5U << 16U) + 6U)
#define sfWalletLocator ((5U << 16U) + 7U)
#define sfRootIndex ((5U << 16U) + 8U)
#define sfAccountTxnID ((5U << 16U) + 9U)
#define sfTokenID ((5U << 16U) + 10U)
#define sfEmitParentTxnID ((5U << 16U) + 11U)
#define sfEmitNonce ((5U << 16U) + 12U)
#define sfEmitHookHash ((5U << 16U) + 13U)
#define sfBookDirectory ((5U << 16U) + 16U)
#define sfInvoiceID ((5U << 16U) + 17U)
#define sfNickname ((5U << 16U) + 18U)
#define sfAmendment ((5U << 16U) + 19U)
#define sfDigest ((5U << 16U) + 21U)
#define sfChannel ((5U << 16U) + 22U)
#define sfConsensusHash ((5U << 16U) + 23U)
#define sfCheckID ((5U << 16U) + 24U)
#define sfValidatedHash ((5U << 16U) + 25U)
#define sfPreviousPageMin ((5U << 16U) + 26U)
#define sfNextPageMin ((5U << 16U) + 27U)
#define sfBuyOffer ((5U << 16U) + 28U)
#define sfSellOffer ((5U << 16U) + 29U)
#define sfHookStateKey ((5U << 16U) + 30U)
#define sfHookHash ((5U << 16U) + 31U)
#define sfHookNamespace ((5U << 16U) + 32U)
#define sfHookSetTxnID ((5U << 16U) + 33U)
#define sfAmount ((6U << 16U) + 1U)
#define sfBalance ((6U << 16U) + 2U)
#define sfLimitAmount ((6U << 16U) + 3U)
#define sfTakerPays ((6U << 16U) + 4U)
#define sfTakerGets ((6U << 16U) + 5U)
#define sfLowLimit ((6U << 16U) + 6U)
#define sfHighLimit ((6U << 16U) + 7U)
#define sfFee ((6U << 16U) + 8U)
#define sfSendMax ((6U << 16U) + 9U)
#define sfDeliverMin ((6U << 16U) + 10U)
#define sfMinimumOffer ((6U << 16U) + 16U)
#define sfRippleEscrow ((6U << 16U) + 17U)
#define sfDeliveredAmount ((6U << 16U) + 18U)
#define sfBrokerFee ((6U << 16U) + 19U)
#define sfPublicKey ((7U << 16U) + 1U)
#define sfMessageKey ((7U << 16U) + 2U)
#define sfSigningPubKey ((7U << 16U) + 3U)
#define sfTxnSignature ((7U << 16U) + 4U)
#define sfURI ((7U << 16U) + 5U)
#define sfSignature ((7U << 16U) + 6U)
#define sfDomain ((7U << 16U) + 7U)
#define sfFundCode ((7U << 16U) + 8U)
#define sfRemoveCode ((7U << 16U) + 9U)
#define sfExpireCode ((7U << 16U) + 10U)
#define sfCreateCode ((7U << 16U) + 11U)
#define sfMemoType ((7U << 16U) + 12U)
#define sfMemoData ((7U << 16U) + 13U)
#define sfMemoFormat ((7U << 16U) + 14U)
#define sfFulfillment ((7U << 16U) + 16U)
#define sfCondition ((7U << 16U) + 17U)
#define sfMasterSignature ((7U << 16U) + 18U)
#define sfUNLModifyValidator ((7U << 16U) + 19U)
#define sfValidatorToDisable ((7U << 16U) + 20U)
#define sfValidatorToReEnable ((7U << 16U) + 21U)
#define sfHookStateData ((7U << 16U) + 22U)
#define sfHookReturnString ((7U << 16U) + 23U)
#define sfHookParameterName ((7U << 16U) + 24U)
#define sfHookParameterValue ((7U << 16U) + 25U)
#define sfAccount ((8U << 16U) + 1U)
#define sfOwner ((8U << 16U) + 2U)
#define sfDestination ((8U << 16U) + 3U)
#define sfIssuer ((8U << 16U) + 4U)
#define sfAuthorize ((8U << 16U) + 5U)
#define sfUnauthorize ((8U << 16U) + 6U)
#define sfRegularKey ((8U << 16U) + 8U)
#define sfMinter ((8U << 16U) + 9U)
#define sfEmitCallback ((8U << 16U) + 10U)
#define sfHookAccount ((8U << 16U) + 16U)
#define sfIndexes ((19U << 16U) + 1U)
#define sfHashes ((19U << 16U) + 2U)
#define sfAmendments ((19U << 16U) + 3U)
#define sfTokenOffers ((19U << 16U) + 4U)
#define sfPaths ((18U << 16U) + 1U)
#define sfTransactionMetaData ((14U << 16U) + 2U)
#define sfCreatedNode ((14U << 16U) + 3U)
#define sfDeletedNode ((14U << 16U) + 4U)
#define sfModifiedNode ((14U << 16U) + 5U)
#define sfPreviousFields ((14U << 16U) + 6U)
#define sfFinalFields ((14U << 16U) + 7U)
#define sfNewFields ((14U << 16U) + 8U)
#define sfTemplateEntry ((14U << 16U) + 9U)
#define sfMemo ((14U << 16U) + 10U)
#define sfSignerEntry ((14U << 16U) + 11U)
#define sfNonFungibleToken ((14U << 16U) + 12U)
#define sfEmitDetails ((14U << 16U) + 13U)
#define sfHook ((14U << 16U) + 14U)
#define sfSigner ((14U << 16U) + 16U)
#define sfMajority ((14U << 16U) + 18U)
#define sfDisabledValidator ((14U << 16U) + 19U)
#define sfEmittedTxn ((14U << 16U) + 20U)
#define sfHookExecution ((14U << 16U) + 21U)
#define sfHookDefinition ((14U << 16U) + 22U)
#define sfHookParameter ((14U << 16U) + 23U)
#define sfHookGrant ((14U << 16U) + 24U)
#define sfSigners ((15U << 16U) + 3U)
#define sfSignerEntries ((15U << 16U) + 4U)
#define sfTemplate ((15U << 16U) + 5U)
#define sfNecessary ((15U << 16U) + 6U)
#define sfSufficient ((15U << 16U) + 7U)
#define sfAffectedNodes ((15U << 16U) + 8U)
#define sfMemos ((15U << 16U) + 9U)
#define sfNonFungibleTokens ((15U << 16U) + 10U)
#define sfHooks ((15U << 16U) + 11U)
#define sfMajorities ((15U << 16U) + 16U)
#define sfDisabledValidators ((15U << 16U) + 17U)
#define sfHookExecutions ((15U << 16U) + 18U)
#define sfHookParameters ((15U << 16U) + 19U)
#define sfHookGrants ((15U << 16U) + 20U)

137
hook-api-examples/utils-tests.js Normal file
View File

@@ -0,0 +1,137 @@
const fs = require('fs')
const xrpljs = require('xrpl-hooks');
const kp = require('ripple-keypairs');
const { exec } = require('child_process');
// Fails via process.exit
module.exports = {
TestRig: (endpoint)=>
{
return new Promise((resolve, reject)=>
{
const api = new xrpljs.Client(endpoint);
const execShell = cmd =>
{
return new Promise((resolve, reject) =>
{
exec(cmd, (error, stdout, stderr) =>
{
if (error)
{
console.log(error);
process.exit(2);
}
console.log("Ran cmd: `" + cmd + "`");
if (stdout)
console.log("stdout:", stdout);
if (stderr)
console.log("stderr:", stderr);
resolve([stdout, stderr]);
});
});
};
const assertTxnSuccess = x =>
{
if (!x || !x.result || x.result.engine_result_code != 0)
{
console.log("Transaction failed:", x)
process.exit(1);
}
};
const assertTxnFailure = x =>
{
if (!x || !x.result || x.result.engine_result_code == 0)
{
console.log("Transaction failed:", x)
process.exit(1);
}
};
const err = (x) =>
{
console.log(x); process.exit(1);
}
const wasm = (x) =>
{
return fs.readFileSync(x).toString('hex').toUpperCase();
}
const genesis = xrpljs.Wallet.fromSeed('snoPBrXtMeMyMHUVTgbuqAfg1SUTb');
const randomAccount = ()=>
{
return xrpljs.Wallet.fromSeed(kp.generateSeed());
};
const findWasm = ()=>
{
return fs.readdirSync('.').filter(fn => fn.endsWith('.wasm'));
}
const fundFromGenesis = (acc) =>
{
return new Promise((resolve, reject) =>
{
if (typeof(acc) != 'string')
acc = acc.classicAddress;
api.submit({
Account: genesis.classicAddress, // fund account from genesis
TransactionType: "Payment",
Amount: "1000000000",
Destination: acc
}, {wallet: genesis}).then(x=>
{
assertTxnSuccess(x);
resolve(x);
}).catch(err);
});
};
const pay = (seed, amt, dest) =>
{
return new Promise((resolve, reject) =>
{
let wal = xrpljs.Wallet.fromSeed(seed);
api.submit({
Account: wal.classicAddress, // fund account from genesis
TransactionType: "Payment",
Amount: ''+amt,
Destination: dest,
Fee: "10000"
}, {wallet: wal}).then(x=>
{
assertTxnSuccess(x);
resolve(x);
}).catch(err);
});
};
api.connect().then(()=>
{
resolve({
api: api,
xrpljs: xrpljs,
assertTxnSuccess: assertTxnSuccess,
assertTxnFailure: assertTxnFailure,
wasm: wasm,
kp: kp,
genesis: genesis,
randomAccount: randomAccount,
fundFromGenesis: fundFromGenesis,
err: err,
hsfOVERRIDE: 1,
hsfNSDELETE: 2,
pay: pay,
findWasm: findWasm,
execShell: execShell
});
}).catch(err);
});
}
};