hooks_rs/api/
control.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
use crate::c;

// Safe to be modified globally because wasm is guaranteed to run in a single thread
static mut GUARD_ID: u32 = 0;

/// Guard function
///
/// Each time a loop appears in your code a call to this must be
/// the first branch instruction in wasm binary after the beginning of the loop.
/// In order to achieve this in Rust use the `while` loop with expression block.
///
/// # Example
///
/// ```no_run
/// let mut i = 0;
/// while {
///     _g(UNIQUE_GUARD_ID, MAXITER + 1);
///     i < MAXITER
/// } {
///     // your code
///     i += 1;
/// }
/// ```
#[cfg(not(doctest))]
#[inline(always)]
pub fn _g(id: u32, max_iter: u32) {
    unsafe {
        c::_g(id, max_iter);
    }
}

/// Instead of having to pass the `GUARD_ID` parameter to every call to `_g`,
/// you can use this function to generate a unique `GUARD_ID` for each call
/// automatically.
///
/// # Example
///
/// ```no_run
/// let mut i = 0;
/// while {
///     max_iter(MAXITER + 1);
///     i < MAXITER
/// } {
///     // your code
///     i += 1;
/// }
/// ```
#[inline(always)]
pub fn max_iter(max_iter: u32) {
    unsafe {
        // TODO: this is not quite right, because this will be called
        // every single time the loop is entered, not just the first time.
        //
        // Fortunately enough, XRPL nodes will not care about this problem
        // when validating SetHook payload of this function included.
        // However it adds an overhead to the code that is not necessary.
        //
        // To solve this problem, we will need to use a macro that would
        // increment a unique GUARD_ID for each while statement and put it
        // into the condition statement, so that it could be called like:
        // while_loop! { ( some_condition ) { ... } }
        GUARD_ID += 1;
        _g(GUARD_ID, max_iter);
    }
}

/// Accept the originating transaction and commit any changes the hook made
///
/// # Example
///
/// You can use a byte string to return a message
/// ```
/// accept(b"accept.rs: Finished.", line!().into());
/// ```
///
/// You can also return any forms of bytes, like:
/// ```
/// let txn_hash = match emit(&xrp_payment_txn) {
///     Ok(hash) => hash,
///     Err(err) => {
///         rollback(b"could not emit xrp payment txn", err.into());
///     }
/// };
/// accept(&txn_hash, 0);
/// ```
#[inline(always)]
pub fn accept(msg: &[u8], error_code: i64) -> ! {
    unsafe {
        c::accept(msg.as_ptr() as u32, msg.len() as u32, error_code);
        core::hint::unreachable_unchecked()
    }
}

/// Reject the originating transaction and discard any changes the hook made
///
/// # Example
/// ```
/// rollback(b"encountered a problem", -1)
/// ```
#[inline(always)]
pub fn rollback(msg: &[u8], error_code: i64) -> ! {
    unsafe {
        c::rollback(msg.as_ptr() as u32, msg.len() as u32, error_code);
        core::hint::unreachable_unchecked()
    }
}