# XRPL Hooks - Smart Contract proposal for the XRP Ledger Documentation

> Hooks add smart contract functionality to the XRP Ledger: 'layer one' custom code to influence the behaviour and flow of transactions. Hooks are small, efficient pieces of code being defined on an XRPL account, allowing logic to be executed before and/or after XRPL transactions. The XRP ledger is known and is being appreciated for its transaction throughput, speed and the low fees. Combined with available advanced transaction types like multi sign, escrows, payment channels and even a decentralized exchange (all on ledger, out of the box, without requiring smart contracts) the XRPL has a lot to offer businesses and (creative) developers.

## Guides
- [Introduction](https://xrpl-hooks.readme.io/docs/introduction.md): Hooks add smart contract functionality to the XRP Ledger: _layer one_ custom code to influence the behaviour and flow of transactions. Hooks are small, efficient pieces of code being defined on an XRPL account, allowing logic to be executed before and/or after XRPL transactions.
- [Example Usage](https://xrpl-hooks.readme.io/docs/examples.md)
- [Terminology](https://xrpl-hooks.readme.io/docs/introduction-and-terminology.md): Welcome to Hooks 👋
- [Loops and Guarding](https://xrpl-hooks.readme.io/docs/loops-and-guarding.md): Guards are needed to perform loops in a Hook.
- [Compiling Hooks](https://xrpl-hooks.readme.io/docs/compiling-hooks.md): How to build a Hook, and what a built Hook looks like.
- [Chaining](https://xrpl-hooks.readme.io/docs/hook-chaining.md): Chain multiple hooks together to do more useful tasks
- [Weak and Strong](https://xrpl-hooks.readme.io/docs/transactional-stake-holders.md): Which Hooks are allowed to run and when?
- [Collect Call](https://xrpl-hooks.readme.io/docs/collect-call-hooks.md): When does the originating transaction NOT pay for a Hook execution?
- [SetHook Transaction](https://xrpl-hooks.readme.io/docs/sethook-transaction.md): A new Transaction Type for the XRPL that sets a Hook onto an XRPL account.
- [Parameters](https://xrpl-hooks.readme.io/docs/parameters.md): Install-time parameters allow Hooks to be generic and flexible
- [Namespaces](https://xrpl-hooks.readme.io/docs/namespaces.md): Prevent state clobbering by using the correct namespace
- [Grants](https://xrpl-hooks.readme.io/docs/grants.md): Hook Grants
- [HookOn Field](https://xrpl-hooks.readme.io/docs/hookon-field.md): Specify which transaction types a Hook should be triggered on
- [Reference Counting](https://xrpl-hooks.readme.io/docs/reference-counting.md): Avoid re-uploading the same bytecode to the ledger
- [Hook Fees](https://xrpl-hooks.readme.io/docs/hook-fees.md): What to expect when your Hook runs.
- [Execution Metadata](https://xrpl-hooks.readme.io/docs/execution-order.md): What to expect when your Hook runs.
- [Debugging Hooks](https://xrpl-hooks.readme.io/docs/trace-debugging.md): How to print "hello world" from your Hook!
- [State Management](https://xrpl-hooks.readme.io/docs/state-management.md): Hooks can read and save small pieces of on-ledger data 🚀
- [Slots and Keylets](https://xrpl-hooks.readme.io/docs/slots-and-keylets.md): Inspect and manipulate on-ledger objects.
- [Floating Point Numbers (XFL)](https://xrpl-hooks.readme.io/docs/floating-point-numbers-xfl.md): High precision calculations are native to Hooks.
- [Emitted Transactions](https://xrpl-hooks.readme.io/docs/emitted-transactions.md): Your Hook can do a lot more than just block or allow transactions!
- [Serialized Objects](https://xrpl-hooks.readme.io/docs/serialized-objects.md): Manipulate raw serialized xrpld objects!

## API Reference
- [Hook API Conventions](https://xrpl-hooks.readme.io/reference/hook-api-conventions.md)
- [Return Codes](https://xrpl-hooks.readme.io/reference/negative-return-codes.md): A list of possible errors returned by Hook APIs.
- [hook](https://xrpl-hooks.readme.io/reference/hook.md): The main function of your hook
- [cbak](https://xrpl-hooks.readme.io/reference/cbak.md): The callback function of your hook
- [accept](https://xrpl-hooks.readme.io/reference/accept.md): Accept the originating transaction and commit any changes the hook made.
- [rollback](https://xrpl-hooks.readme.io/reference/rollback.md): Reject the originating transaction and discard any changes the hook made.
- [util_raddr](https://xrpl-hooks.readme.io/reference/util_raddr.md): Convert a 20 byte Account ID to an r-address
- [util_accid](https://xrpl-hooks.readme.io/reference/util_accid.md): Convert an r-address into a 20 byte Account ID
- [util_verify](https://xrpl-hooks.readme.io/reference/util_verify.md): Verify a cryptographic signature
- [util_sha512h](https://xrpl-hooks.readme.io/reference/util_sha512h.md): Compute an sha512-half over some data
- [util_keylet](https://xrpl-hooks.readme.io/reference/util_keylet.md): Compute a serialized keylet of a given type
- [sto_subfield](https://xrpl-hooks.readme.io/reference/sto_subfield.md): Index into a xrpld serialized object and return the location and length of a subfield
- [sto_subarray](https://xrpl-hooks.readme.io/reference/sto_subarray.md): Index into a xrpld serialized array and return the location and length of an index
- [sto_emplace](https://xrpl-hooks.readme.io/reference/sto_emplace.md): Emplace a field into an existing STObject at its canonical placement
- [sto_erase](https://xrpl-hooks.readme.io/reference/sto_erase.md): Remove a field from an STObject
- [sto_validate](https://xrpl-hooks.readme.io/reference/sto_validate.md): Validate an STObject
- [etxn_burden](https://xrpl-hooks.readme.io/reference/etxn_burden.md): Get the burden of a hypothetically emitted transaction
- [etxn_details](https://xrpl-hooks.readme.io/reference/etxn_details.md): Produce an sfEmitDetails suitable for a soon-to-be emitted transaction
- [etxn_fee_base](https://xrpl-hooks.readme.io/reference/etxn_fee_base.md): Estimate the required fee for a txn to be emitted successfully
- [etxn_nonce](https://xrpl-hooks.readme.io/reference/nonce.md): Generate a 32 byte nonce for use in an emitted transaction
- [etxn_reserve](https://xrpl-hooks.readme.io/reference/etxn_reserve.md): Estimate the required fee for a txn to be emitted successfully
- [etxn_generation](https://xrpl-hooks.readme.io/reference/etxn_generation.md): Get the generation of a hypothetically emitted transaction
- [emit](https://xrpl-hooks.readme.io/reference/emit.md): Emit a new transaction from the hook
- [float_set](https://xrpl-hooks.readme.io/reference/float_set.md): Create a float from an exponent and mantissa
- [float_multiply](https://xrpl-hooks.readme.io/reference/float_multiply.md): Multiply two XFL numbers together
- [float_mulratio](https://xrpl-hooks.readme.io/reference/float_mulratio.md): Multiply an XFL floating point by a non-XFL numerator and denominator
- [float_negate](https://xrpl-hooks.readme.io/reference/float_negate.md): Negate an XFL floating point number
- [float_compare](https://xrpl-hooks.readme.io/reference/float_compare.md): Perform a comparison on two XFL floating point numbers
- [float_sum](https://xrpl-hooks.readme.io/reference/float_sum.md): Add two XFL numbers together
- [float_sto](https://xrpl-hooks.readme.io/reference/float_sto.md): Output an XFL as a serialized object
- [float_sto_set](https://xrpl-hooks.readme.io/reference/float_sto_set.md): Read a serialized amount into an XFL
- [float_invert](https://xrpl-hooks.readme.io/reference/float_invert.md): Divide one by an XFL floating point number
- [float_divide](https://xrpl-hooks.readme.io/reference/float_divide.md): Divide an XFL by another XFL floating point number
- [float_one](https://xrpl-hooks.readme.io/reference/float_one.md): Return the number 1 represented in an XFL enclosing number
- [float_exponent](https://xrpl-hooks.readme.io/reference/float_exponent.md): Get the exponent of an XFL enclosing number
- [float_mantissa](https://xrpl-hooks.readme.io/reference/float_mantissa.md): Get the mantissa of an XFL enclosing number
- [float_sign](https://xrpl-hooks.readme.io/reference/float_sign.md): Get the sign of an XFL enclosing number
- [float_int](https://xrpl-hooks.readme.io/reference/float_int.md): Convert an XFL floating point into an integer (floor)
- [float_root](https://xrpl-hooks.readme.io/reference/float_sqrt.md): Compute the nth root of an XFL
- [float_log](https://xrpl-hooks.readme.io/reference/float_log.md): Compute the decimal log of an XFL
- [fee_base](https://xrpl-hooks.readme.io/reference/fee_base.md): Fetch the fee base of the current ledger
- [ledger_seq](https://xrpl-hooks.readme.io/reference/ledger_seq.md): Fetch the current ledger sequence number
- [ledger_last_hash](https://xrpl-hooks.readme.io/reference/ledger_last_hash.md): Retreive the 32 byte namespace biased SHA512H of the last closed ledger
- [ledger_last_time](https://xrpl-hooks.readme.io/reference/ledger_last_time.md): Fetch the last closed ledger's timestamp
- [ledger_nonce](https://xrpl-hooks.readme.io/reference/ledger_nonce.md): Generate a 32 byte nonce for use in an emitted transaction
- [ledger_keylet](https://xrpl-hooks.readme.io/reference/ledger_keylet.md): Search for a keylet within a specified range on the current ledger
- [hook_account](https://xrpl-hooks.readme.io/reference/hook_account.md): Retreive the 20 byte Account ID the Hook is executing on
- [hook_hash](https://xrpl-hooks.readme.io/reference/hook_hash.md): Retreive the 32 byte namespace biased SHA512H of the currently executing Hook
- [hook_param](https://xrpl-hooks.readme.io/reference/hook_param.md): Retrieve the parameter value for a named hook parameter
- [hook_param_set](https://xrpl-hooks.readme.io/reference/hook_param_set.md): Set or delete a parameter on a hook on the same account further down the execution chain
- [hook_skip](https://xrpl-hooks.readme.io/reference/hook_skip.md): Skip a hook that appears later in the hook chain on the hook account
- [hook_pos](https://xrpl-hooks.readme.io/reference/hook_pos.md): Returns the position in the hook chain the currently executing hook occupies
- [hook_again](https://xrpl-hooks.readme.io/reference/hook_again.md): Returns the position in the hook chain the currently executing hook occupies
- [slot](https://xrpl-hooks.readme.io/reference/slot.md): Serialize and output a slotted object
- [slot_clear](https://xrpl-hooks.readme.io/reference/slot_clear.md): Free up a currently occupied slot
- [slot_count](https://xrpl-hooks.readme.io/reference/slot_count.md): Count the elements of an array object in a slot
- [slot_set](https://xrpl-hooks.readme.io/reference/slot_set.md): Locate an object based on its keylet and place it into a slot
- [slot_size](https://xrpl-hooks.readme.io/reference/slot_size.md): Compute the serialized size of an object in a slot
- [slot_subarray](https://xrpl-hooks.readme.io/reference/slot_subarray.md): Index into a slotted array and assign a sub-object to another slot
- [slot_subfield](https://xrpl-hooks.readme.io/reference/slot_subfield.md): Index into a slotted object and assign a sub-object to another slot
- [slot_type](https://xrpl-hooks.readme.io/reference/slot_type.md): Retrieve the field code of an object in a slot and, optionally, some other information
- [xpop_slot](https://xrpl-hooks.readme.io/reference/xpop_slot.md): Serialize and output the xpop transaction blob and metadata
- [slot_float](https://xrpl-hooks.readme.io/reference/slot_float.md): Parse the STI_AMOUNT in the specified slot and return it as an XFL enclosed number
- [state](https://xrpl-hooks.readme.io/reference/state.md): Retrieve the data pointed to by a Hook State key and write it to an output buffer
- [state_set](https://xrpl-hooks.readme.io/reference/state_set.md): Set the Hook State for a given key and value
- [state_foreign](https://xrpl-hooks.readme.io/reference/state_foreign.md): Retrieve the data pointed to, on another account, by a Hook State key and write it to an output buffer
- [state_foreign_set](https://xrpl-hooks.readme.io/reference/state_foreign_set.md): Set the Hook State on another account for a given key, value and namespace
- [trace](https://xrpl-hooks.readme.io/reference/trace.md): Write the contents of a buffer to the XRPLD trace log
- [trace_num](https://xrpl-hooks.readme.io/reference/trace_num.md): Write an integer to the XRPLD trace log
- [trace_float](https://xrpl-hooks.readme.io/reference/trace_float.md): Write a XFL float to the XRPLD trace log
- [otxn_burden](https://xrpl-hooks.readme.io/reference/otxn_burden.md): Get the burden of the originating transaction
- [otxn_field](https://xrpl-hooks.readme.io/reference/otxn_field.md): Serialize and output a field from the originating transaction
- [otxn_generation](https://xrpl-hooks.readme.io/reference/otxn_generation.md): Get the generation of the originating transaction
- [otxn_id](https://xrpl-hooks.readme.io/reference/otxn_id.md): Output the canonical hash of the originating transaction
- [otxn_type](https://xrpl-hooks.readme.io/reference/otxn_type.md): Get the Transaction Type of the originating transaction
- [otxn_slot](https://xrpl-hooks.readme.io/reference/otxn_slot.md): Load the originating transaction into a slot
- [otxn_param](https://xrpl-hooks.readme.io/reference/otxn_param.md): Retrieve the parameter value for a named Invoke transaction parameter
- [meta_slot](https://xrpl-hooks.readme.io/reference/meta_slot.md): Load the metadata of the originating transaction into a slot
- [account_info](https://xrpl-hooks.readme.io/reference/account_info.md)
- [account_namespace](https://xrpl-hooks.readme.io/reference/account_namespace.md)

## Changelog
- [2023-02-15 - Hooks V3 Testnet live](https://xrpl-hooks.readme.io/changelog/hooks-v3-testnet-live.md)
- [2022-03-09 - Hooks V2 Testnet live](https://xrpl-hooks.readme.io/changelog/2022-03-09-hooks-v2-testnet-live.md)
- [2022-01-25 - Hook Chaining](https://xrpl-hooks.readme.io/changelog/2022-01-25-hook-chaining.md)
- [2021-05-3 - Breaking API and behaviour changes](https://xrpl-hooks.readme.io/changelog/2021-05-3-breaking-api-and-behaviour-changes.md)
- [2021-04-19 - Hooks Public Testnet live](https://xrpl-hooks.readme.io/changelog/hooks-public-testnet-live.md)