Expand description
§Low-level unsafe C bindings
Use very carefully if at all necessary.
Constants§
- ALREADY_
SET - COMPARE_
EQUAL - COMPARE_
GREATER - COMPARE_
LESS - DOESNT_
EXIST - EMISSION_
FAILURE - ENCODE_
ACCOUNT_ DST_ SIZE - ENCODE_
ACCOUNT_ SIZE - ENCODE_
ACCOUNT_ SRC_ SIZE - ENCODE_
DROPS_ SIZE - ENCODE_
FLAGS_ SIZE - ENCODE_
FLS_ SIZE - ENCODE_
LLS_ SIZE - ENCODE_
SEQUENCE_ SIZE - ENCODE_
SIGNING_ PUBKEY_ NULL_ SIZE - ENCODE_
SIGNING_ PUBKEY_ SIZE - ENCODE_
TAG_ DST_ SIZE - ENCODE_
TAG_ SRC_ SIZE - ENCODE_
TL_ SIZE - ENCODE_
TT_ SIZE - ENCODE_
UINT32_ COMMON_ SIZE - ENCODE_
UINT32_ UNCOMMON_ SIZE - FEE_
TOO_ LARGE - GUARD_
VIOLATION - HOOKAPI_
INCLUDED - HOOKMACROS_
INCLUDED - INT8_
MAX - INT8_
MIN - INT16_
MAX - INT16_
MIN - INT32_
MAX - INT32_
MIN - INTERNAL_
ERROR - INTPTR_
MAX - INTPTR_
MIN - INT_
FAST8_ MAX - INT_
FAST8_ MIN - INT_
FAST16_ MAX - INT_
FAST16_ MIN - INT_
FAST32_ MAX - INT_
FAST32_ MIN - INT_
LEAS T8_ MAX - INT_
LEAS T8_ MIN - INT_
LEAS T16_ MAX - INT_
LEAS T16_ MIN - INT_
LEAS T32_ MAX - INT_
LEAS T32_ MIN - INVALID_
ACCOUNT - INVALID_
ARGUMENT - INVALID_
FIELD - INVALID_
FLOAT - KEYLET_
ACCOUNT - KEYLET_
AMENDMENTS - KEYLET_
CHECK - KEYLET_
CHILD - KEYLET_
DEPOSIT_ PREAUTH - KEYLET_
EMITTED - KEYLET_
EMITTED_ DIR - KEYLET_
ESCROW - KEYLET_
FEES - KEYLET_
HOOK - KEYLET_
HOOK_ STATE - KEYLET_
LINE - KEYLET_
NEGATIVE_ UNL - KEYLET_
OFFER - KEYLET_
OWNER_ DIR - KEYLET_
PAGE - KEYLET_
PAYCHAN - KEYLET_
QUALITY - KEYLET_
SIGNERS - KEYLET_
SKIP - KEYLET_
TICKET - KEYLET_
UNCHECKED - NOT_
IMPLEMENTED - NO_
FREE_ SLOTS - NO_
SUCH_ KEYLET - OUT_
OF_ BOUNDS - PARSE_
ERROR - PREPARE_
PAYMENT_ SIMPLE_ SIZE - PREPARE_
PAYMENT_ SIMPLE_ TRUSTLINE_ SIZE - PREREQUISITE_
NOT_ MET - PTRDIFF_
MAX - PTRDIFF_
MIN - RC_
ACCEPT - RC_
ROLLBACK - SIG_
ATOMIC_ MAX - SIG_
ATOMIC_ MIN - SIZE_
MAX - SUCCESS
- TOO_BIG
- TOO_
MANY_ EMITTED_ TXN - TOO_
MANY_ NONCES - TOO_
SMALL - UINT8_
MAX - UINT16_
MAX - UINT32_
MAX - UINTPTR_
MAX - UINT_
FAST8_ MAX - UINT_
FAST16_ MAX - UINT_
FAST32_ MAX - UINT_
LEAS T8_ MAX - UINT_
LEAS T16_ MAX - UINT_
LEAS T32_ MAX - WINT_
MAX - WINT_
MIN - _ATFILE_
SOURCE - _BITS_
STDINT_ INTN_ H - _BITS_
STDINT_ UINTN_ H - _BITS_
TIME64_ H - _BITS_
TYPESIZES_ H - _BITS_
TYPES_ H - _BITS_
WCHAR_ H - _DEFAULT_
SOURCE - _FEATURES_
H - _POSIX_
C_ SOURCE - _POSIX_
SOURCE - _STDC_
PREDEF_ H - _STDINT_
H - _SYS_
CDEFS_ H - __
FD_ SETSIZE - __
GLIBC_ MINOR__ - __
GLIBC_ USE_ DEPRECATED_ GETS - __
GLIBC_ USE_ DEPRECATED_ SCANF - __
GLIBC_ USE_ IEC_ 60559_ BFP_ EXT - __
GLIBC_ USE_ IEC_ 60559_ BFP_ EXT_ C2X - __
GLIBC_ USE_ IEC_ 60559_ FUNCS_ EXT - __
GLIBC_ USE_ IEC_ 60559_ FUNCS_ EXT_ C2X - __
GLIBC_ USE_ IEC_ 60559_ TYPES_ EXT - __
GLIBC_ USE_ ISOC2X - __
GLIBC_ USE_ LIB_ EXT2 - __
GLIBC__ - __
GNU_ LIBRARY__ - __
HAVE_ GENERIC_ SELECTION - __
INO_ T_ MATCHES_ INO64_ T - __
LONG_ DOUBLE_ USES_ FLOA T128 - __
OFF_ T_ MATCHES_ OFF64_ T - __
RLIM_ T_ MATCHES_ RLIM64_ T - __
STATFS_ MATCHES_ STATF S64 - __
STDC_ IEC_ 559_ COMPLEX__ - __
STDC_ IEC_ 559__ - __
STDC_ ISO_ 10646__ - __
SYSCALL_ WORDSIZE - __
TIMESIZE - __
USE_ ATFILE - __
USE_ FORTIFY_ LEVEL - __
USE_ ISOC11 - __
USE_ ISOC95 - __
USE_ ISOC99 - __
USE_ MISC - __
USE_ POSIX - __
USE_ POSI X2 - __
USE_ POSI X199309 - __
USE_ POSI X199506 - __
USE_ POSIX_ IMPLICITLY - __
USE_ XOPE N2K - __
USE_ XOPE N2K8 - __
WORDSIZE - __
WORDSIZE_ TIME64_ COMPA T32 - __
glibc_ c99_ flexarr_ available - amAMOUNT
- amBALANCE
- amDELIVEREDAMOUNT
- amDELIVERMIN
- amFEE
- amHIGHLIMIT
- amLIMITAMOUNT
- amLOWLIMIT
- amMINIMUMOFFER
- amRIPPLEESCROW
- amSENDMAX
- amTAKERGETS
- amTAKERPAYS
- atACCOUNT
- atAUTHORIZE
- atDESTINATION
- atISSUER
- atOWNER
- atPSEUDOCALLBACK
- atREGULARKEY
- atTARGET
- atUNAUTHORIZE
- sfAccount
- sfAccount
Hash - sfAccount
TxnID - sfAffected
Nodes - sfAmendment
- sfAmendments
- sfAmount
- sfAuthorize
- sfBalance
- sfBase
Fee - sfBond
Amount - sfBook
Directory - sfBook
Node - sfCancel
After - sfCheckID
- sfClear
Flag - sfClose
Resolution - sfClose
Time - sfCondition
- sfConsensus
Hash - sfCookie
- sfCreate
Code - sfCreated
Node - sfDeleted
Node - sfDeliver
Min - sfDelivered
Amount - sfDestination
- sfDestination
Node - sfDestination
Tag - sfDigest
- sfDomain
- sfEmail
Hash - sfEmit
Burden - sfEmit
Details - sfEmit
Generation - sfEmit
Nonce - sfEmit
Parent TxnID - sfExchange
Rate - sfExpiration
- sfExpire
Code - sfFee
- sfFinal
Fields - sfFinish
After - sfFirst
Ledger Sequence - sfFlags
- sfFulfillment
- sfFund
Code - sfGeneric
- sfHash
- sfHashes
- sfHigh
Limit - sfHigh
Node - sfHigh
Quality In - sfHigh
Quality Out - sfHook
Data - sfHook
Data MaxSize - sfHook
On - sfHook
Reserve Count - sfHook
State Count - sfIndex
- sfIndex
Next - sfIndex
Previous - sfIndexes
- sfInvalid
- sfInvoiceID
- sfIssuer
- sfLast
Ledger Sequence - sfLedger
Entry - sfLedger
Entry Type - sfLedger
Hash - sfLedger
Index - sfLedger
Sequence - sfLimit
Amount - sfLoad
Fee - sfLow
Limit - sfLow
Node - sfLow
Quality In - sfLow
Quality Out - sfMajorities
- sfMajority
- sfMaster
Signature - sfMemo
- sfMemo
Data - sfMemo
Format - sfMemo
Type - sfMemos
- sfMessage
Key - sfMetadata
- sfMethod
- sfMinimum
Offer - sfModified
Node - sfNecessary
- sfNegativeUNL
- sfNegativeUNL
Entry - sfNegativeUNL
ToDisable - sfNegativeUNL
ToRe Enable - sfNew
Fields - sfNickname
- sfOffer
Sequence - sfOperation
Limit - sfOwner
- sfOwner
Count - sfOwner
Node - sfParent
Close Time - sfParent
Hash - sfPaths
- sfPay
Channel - sfPrevious
Fields - sfPrevious
TxnID - sfPrevious
TxnLgr Seq - sfPublic
Key - sfQuality
In - sfQuality
Out - sfReference
FeeUnits - sfRegular
Key - sfRemove
Code - sfReserve
Base - sfReserve
Increment - sfRipple
Escrow - sfRoot
Index - sfSend
Max - sfSequence
- sfServer
Version - sfSet
Flag - sfSettle
Delay - sfSignature
- sfSigner
- sfSigner
Entries - sfSigner
Entry - sfSigner
ListID - sfSigner
Quorum - sfSigner
Weight - sfSigners
- sfSigning
Accounts - sfSigning
PubKey - sfSigning
Time - sfSource
Tag - sfStamp
Escrow - sfSufficient
- sfTaker
Gets - sfTaker
Gets Currency - sfTaker
Gets Issuer - sfTaker
Pays - sfTaker
Pays Currency - sfTaker
Pays Issuer - sfTarget
- sfTemplate
- sfTemplate
Entry - sfTick
Size - sfTicketID
- sfTransaction
- sfTransaction
Hash - sfTransaction
Index - sfTransaction
Meta Data - sfTransaction
Result - sfTransaction
Type - sfTransfer
Rate - sfTxn
Signature - sfUNL
Modify Disabling - sfUNL
Modify Validator - sfUnauthorize
- sfValidated
Hash - sfValidation
- sfVersion
- sfWallet
Locator - sfWallet
Size - tfCANONICAL
- ttPAYMENT
Functions§
- _g⚠
- 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.
- accept⚠
- 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.
- cbak⚠
- emit⚠
- 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.
- etxn_
burden ⚠ - Compute burden for an emitted transaction. @return the burden a theoretically emitted transaction would have.
- etxn_
details ⚠ - 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.
- etxn_
fee_ ⚠base - 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
- etxn_
generation ⚠ - 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.
- etxn_
reserve ⚠ - 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
- fee_
base ⚠ - Retrive the currently recommended minimum fee for a transaction to succeed.
- float_
compare ⚠ - float_
divide ⚠ - float_
exponent ⚠ - float_
exponent_ ⚠set - float_
int ⚠ - float_
invert ⚠ - float_
mantissa ⚠ - float_
mantissa_ ⚠set - float_
mulratio ⚠ - float_
multiply ⚠ - float_
negate ⚠ - float_
one ⚠ - float_
set ⚠ - float_
sign ⚠ - float_
sign_ ⚠set - float_
sto ⚠ - float_
sto_ ⚠set - float_
sum ⚠ - hook⚠
- hook_
account ⚠ - 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.
- hook_
hash ⚠ - 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.
- ledger_
last_ ⚠hash - ledger_
seq ⚠ - Retrieve the current ledger sequence number
- nonce⚠
- 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.
- otxn_
burden ⚠ - Retrieve the burden of the originating transaction (if any) @return The burden of the originating transaction
- otxn_
field ⚠ - 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.
- otxn_
field_ ⚠txt - 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.
- otxn_
generation ⚠ - Retrieve the generation of the originating transaction (if any). @return the generation of the originating transaction.
- otxn_id⚠
- 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.
- otxn_
slot ⚠ - otxn_
type ⚠ - Retrieve the Transaction Type (e.g. ttPayment = 0) of the originating transaction. @return The Transaction Type (tt-code)
- rollback⚠
- 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.
- slot⚠
- Slot functions have not been implemented yet and the api for them is subject to change
- slot_
clear ⚠ - slot_
count ⚠ - slot_
float ⚠ - slot_id⚠
- slot_
set ⚠ - slot_
size ⚠ - slot_
subarray ⚠ - slot_
subfield ⚠ - slot_
type ⚠ - state⚠
- 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.
- state_
foreign ⚠ - 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.
- state_
set ⚠ - 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
- sto_
emplace ⚠ - sto_
erase ⚠ - sto_
subarray ⚠ - 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.)
- sto_
subfield ⚠ - 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.)
- sto_
validate ⚠ - trace⚠
- 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.
- trace_
float ⚠ - trace_
num ⚠ - 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
- trace_
slot ⚠ - util_
accid ⚠ - 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.
- util_
keylet ⚠ - util_
raddr ⚠ - 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.
- util_
sha512h ⚠ - 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.
- util_
verify ⚠ - 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.