All Hook APIs follow a standard naming convention:
namespace
[ _ noun #1 ]
[ _ verb ]
[ _ noun #2 ]
This may look confusing at first but is actually quite simple:
If the first noun is missing then it is implicitly the same as the namespace
If the verb is missing then it is implicitly get
Thus:
state() means: fetch a hook state.
state_set() means: set a hook.
state_foreign() means: fetch a foreign hook state.
Each Hook executes as a singular stack frame. All working memory must exist within this stackframe. There is no heap and no dynamic memory.
When Hooks communicate with xahaud they can only pass integer values. Typically these integers are pointers within the Hook's memory. Since the Hook runs within xahaud, these points can then be resolved by xahaud and written to or read from as needed to perform the Hook API function.
Only two functions are allowed within a Hook: hook() and cbak(). Read about this here
All parameters passed to a Hook API must be one of: uint32_t, int32_t, uint64_t, int64_t. Typically these are pointers and lengths of buffers within the Hook's stack frame. Sometimes they are Integer Encoded Floating Point Numbers (XFL) or other data.
The parameters to a Hook API are always in the following order:
Writing pointer if any
Writing length if any
Reading pointer if any
Reading length if any
Specifics / other fields if any
Some Hook APIs may only write or may only read from memory, and some might not do either and return a value only by return code.
All Hook APIs return a signed integer. Read about return codes here: Return codes
Web assembly allows for exceptions (traps) however this language feature is not used for Hooks. Instead there is only one way to return from any Hook API (you may think of every Hook API as being noexcept).
To provide for efficient error handling:
All Hook API functions return a signed integer.
All negative return codes are an error.
All return codes 0 or greater are a function specific output, usually but not always the number of bytes read or written.
Error codes are global across all Hook APIs and may be found in the table below.
SUCCESS
>= 0
Non-negative return codes refer always to success and usually indicate the number of bytes written or events performed, depending on the specific API.
OUT_OF_BOUNDS
-1
A pointer or buffer length provided as a parameter described memory outside of the Hook's allowed memory region.
INTERNAL_ERROR
-2
Reserved for internal invariant trips, generally unrelated to inputs. These should be reported with an issue.
TOO_BIG
-3
Attempted to set a parameter or value larger than the allowed space.
TOO_SMALL
-4
The API was unable to produce output to the write_ptr because the specified write_len was too small.
DOESNT_EXIST
-5
The requested object or item wasn't found.
NO_FREE_SLOTS
-6
The Hook attempted to allocate an item into a slot, but there were no slots free. To avoid ensure re-use of existing slots. The maximum number of slots is 255.
INVALID_ARGUMENT
-7
One or more of the parameters to the API were invalid according to the individual API's specification.
ALREADY_SET
-8
Some APIs allow for a once-per-execution parameter to be set. A second attempt to set a once-per-execution parameter results in this error.
PREREQUISITE_NOT_MET
-9
An API required the Hook to do something before the API is allowed to be called. Check the API's documentation.
FEE_TOO_LARGE
-10
During fee calculation if an absurdly large fee is calculated this error is returned.
EMISSION_FAILURE
-11
An attempt to emit() a TXN was unsccessful for any of a number of reasons. Check the trace log of the rippled to which you are submitting the originating TXN.
TOO_MANY_NONCES
-12
A Hook may only use up to 256 calls to nonce() per execution. Further calls result in this error code.
TOO_MANY_EMITTED_TXN
-13
A Hook must declare ahead of time how many TXN it intends to emit().
If it emits fewer than this many, this is allowed.
If it emits more than this many this error is returned.
NOT_IMPLEMENTED
-14
While Hooks is/was in development an API may return this if some or all of that API is planned but not yet implemented.
INVALID_ACCOUNT
-15
An API which accepts a 20 byte Account ID may return this if, in its opinion, the Account ID was not valid for any reason.
GUARD_VIOLATION
-16
All loops inside a Hook must declare at the top of the loop, as the first non trivial instruction, before any branch instruction, the promised maximum number of iterations of the loop. If this promise is violated the hook terminates immediately with this error code.
INVALID_FIELD
-17
The requested serialized field could not be found in the specified object.
PARSE_ERROR
-18
While parsing serialized content an error was encountered (typically indicating an invalidly serialized object).
RC_ROLLBACK
-19
Used internally to communicate a rollback event.
RC_ACCEPT
-20
Used internally to communicate an accept event.
NO_SUCH_KEYLET
-21
Specified keylet could not be found, or keylet is invalid
NOT_AN_ARRAY
-22
API was asked to assume object under analysis is an STArray but it was not.
NOT_AN_OBJECT
-23
API was asked to assume object under analysis is an STObject but it was not.
INVALID_FLOAT
-10024
A floating point operation resulted in Not-A-Number or API call attempted to specify an XFL floating point number outside of the expressible range of XFL.
DIVISION_BY_ZERO
-25
API call would result in a division by zero, so API ended early.
MANITSSA_OVERSIZED
-26
When attempting to create an XFL the mantissa must be 16 decimal digits.
MANTISSA_UNDERSIZED
-27
When attempting to create an XFL the mantissa must be 16 decimal digits.
EXPONENT_OVERSIZED
-28
When attempting to create an XFL the exponent must not exceed 80.
EXPONENT_UNDERSIZED
-29
When attempting to create an XFL the exponent must not be less than -96.
OVERFLOW
-30
A floating point operation done on an XFL resulted in a value larger than XFL format is able to represent.
NOT_IOU_AMOUNT
-31
An API assumed an STAmount was an IOU when in fact it was XRP.
NOT_AN_AMOUNT
-32
An API assumed an STObject was an STAmount when in fact it was not.
CANT_RETURN_NEGATIVE
-33
An API would have returned a negative integer except that negative integers are reserved for error codes (i.e. what you are reading.)
NOT_AUTHORIZED
-34
Hook attempted to set foreign state but was not authorized to do so (grant was missing or invalid.)
PREVIOUS_FAILURE_PREVENTS_RETRY
-35
Hook previously received a NOT_AUTHORIZED return code and is not allowed to retry.
TOO_MANY_PARAMS
-36
Attempted to set a hook parameter for a later hook in the chain, but there are now too many parameters.
INVALID_TXN
-37
Serialized transaction was not a valid transaction (usually because of a missing required field or data corruption / truncation.)
RESERVE_INSUFFICIENT
-38
Setting an additional state object on this account would cause the reserve requirements to exceed the account's balance.
COMPLEX_NOT_SUPPORTED
-39
Hook API would be forced to return a complex number, which it cannot do.
DOES_NOT_MATCH
-40
Two arguments were required to be of the same type but are not.
INVALID_KEY
-41
The provided public key was not valid.
NOT_A_STRING
-42
The buffer did not contain a nul terminated string.
MEM_OVERLAP
-43
The writing pointer points to a buffer that overlaps with the reading pointer.
TOO_MANY_STATE_MODIFICATIONS
-44
More than 5000 modified state entries in the combined hook chains
TOO_MANY_NAMESPACES
-45
More than 256 namespaces on this account