diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ecb7505..2ddc6a8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: CI +name: Build and Test on: push: @@ -11,7 +11,7 @@ concurrency: cancel-in-progress: true jobs: - build: + build-and-test: runs-on: ubuntu-latest steps: @@ -35,3 +35,9 @@ jobs: - name: Build Astro project run: npm run build + + - name: Run HTML Link test + run: | + curl https://htmltest.wjdp.uk | bash + echo "IgnoreDirectoryMissingTrailingSlash: True" > .htmltest.yml + ./bin/htmltest --conf .htmltest.yml --skip-external dist diff --git a/.gitignore b/.gitignore index 16d54bb..0c6b8aa 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,8 @@ pnpm-debug.log* # jetbrains setting folder .idea/ + +# htmltest +/bin/htmltest +/tmp/.htmltest +.htmltest.yml diff --git a/src/content/docs/docs/assets/cdn.feather-2.webp b/public/assets/cdn.feather-2.webp similarity index 100% rename from src/content/docs/docs/assets/cdn.feather-2.webp rename to public/assets/cdn.feather-2.webp diff --git a/public/assets/hook-examples-senarios-1.png b/public/assets/hook-examples-senarios-1.png new file mode 100644 index 0000000..a1e75cd Binary files /dev/null and b/public/assets/hook-examples-senarios-1.png differ diff --git a/public/assets/hook-examples-senarios-2.png b/public/assets/hook-examples-senarios-2.png new file mode 100644 index 0000000..3bc9ae2 Binary files /dev/null and b/public/assets/hook-examples-senarios-2.png differ diff --git a/public/assets/hook-examples-senarios-3.png b/public/assets/hook-examples-senarios-3.png new file mode 100644 index 0000000..23b9f7c Binary files /dev/null and b/public/assets/hook-examples-senarios-3.png differ diff --git a/public/assets/hook-examples-senarios-4.png b/public/assets/hook-examples-senarios-4.png new file mode 100644 index 0000000..6f28a30 Binary files /dev/null and b/public/assets/hook-examples-senarios-4.png differ diff --git a/public/assets/hook-examples-senarios-5.png b/public/assets/hook-examples-senarios-5.png new file mode 100644 index 0000000..6f28a30 Binary files /dev/null and b/public/assets/hook-examples-senarios-5.png differ diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_6S9mLMliCrlQ5JqjDld6_909b3a9-4.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_6S9mLMliCrlQ5JqjDld6_909b3a9-4.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_6S9mLMliCrlQ5JqjDld6_909b3a9-4.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_6S9mLMliCrlQ5JqjDld6_909b3a9-4.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_FvVVFLYOs9skdbzL2PbX_468e0b5-3.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_FvVVFLYOs9skdbzL2PbX_468e0b5-3.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_FvVVFLYOs9skdbzL2PbX_468e0b5-3.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_FvVVFLYOs9skdbzL2PbX_468e0b5-3.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_NbV5W3McCRKkL4eJeF6v_cdf692e-sethook.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_NbV5W3McCRKkL4eJeF6v_cdf692e-sethook.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_NbV5W3McCRKkL4eJeF6v_cdf692e-sethook.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_NbV5W3McCRKkL4eJeF6v_cdf692e-sethook.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_TlDL7tsVNYi1yU64EZQh_3ef0cee-sethook-Page-2.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_TlDL7tsVNYi1yU64EZQh_3ef0cee-sethook-Page-2.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_TlDL7tsVNYi1yU64EZQh_3ef0cee-sethook-Page-2.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_TlDL7tsVNYi1yU64EZQh_3ef0cee-sethook-Page-2.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_VXmzY1NcJIEjMtFsdj5y_08dee14-2.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_VXmzY1NcJIEjMtFsdj5y_08dee14-2.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_VXmzY1NcJIEjMtFsdj5y_08dee14-2.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_VXmzY1NcJIEjMtFsdj5y_08dee14-2.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_XJgZhbZv8VsmtWVy9H73_d404753-1.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_XJgZhbZv8VsmtWVy9H73_d404753-1.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_XJgZhbZv8VsmtWVy9H73_d404753-1.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_XJgZhbZv8VsmtWVy9H73_d404753-1.png diff --git a/src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_sEBiInWuRskTqxB29Xgd_7359187-Hooks_High_Level2x_1.png b/public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_sEBiInWuRskTqxB29Xgd_7359187-Hooks_High_Level2x_1.png similarity index 100% rename from src/content/docs/docs/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_sEBiInWuRskTqxB29Xgd_7359187-Hooks_High_Level2x_1.png rename to public/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_sEBiInWuRskTqxB29Xgd_7359187-Hooks_High_Level2x_1.png diff --git a/src/content/docs/docs/features/amendments.mdx b/src/content/docs/docs/features/amendments.mdx index db7cf5b..d5b7b2b 100644 --- a/src/content/docs/docs/features/amendments.mdx +++ b/src/content/docs/docs/features/amendments.mdx @@ -54,3 +54,131 @@ You can unblock amendment blocked servers by upgrading to the newest version of When amendments are enabled, the source code for pre-amendment behaviors remain in `xahaud`. While there are use-cases for keeping old code, such as reconstructing ledger outcomes for verification, tracking amendments and legacy code adds complexity over time. The [XRP Ledger Standard 11d](https://github.com/XRPLF/XRPL-Standards/discussions/19) defines a process for retiring old amendments and associated pre-amendment code. After an amendment has been enabled on the Mainnet for two years, it can be retired. Retiring an amendment makes it part of the core protocol unconditionally; it's no longer tracked or treated as an amendment, and all pre-amendment code is removed. + +### Known Amendments + +The following amendments have been implemented or are in the process of being enabled on Xahau: + +#### Feature Amendments + +##### XahauGenesis + +Enables the genesis account to mint XAH and distribute it via [GenesisMint transactions](/docs/protocol-reference/transactions/transaction-types/genesismint-emitted-txn). + +##### MultiSign + +Enables multi-signature functionality, allowing accounts to require multiple signatures for transactions. This amendment introduces [SignerListSet transactions](/docs/protocol-reference/transactions/transaction-types/signerlistset) and [SignerList ledger objects](/docs/protocol-reference/ledger-data/ledger-objects-types/signers-list) to support multi-signing. + +##### DepositAuth + +Enables deposit authorization functionality, allowing accounts to require preauthorization before receiving payments. This amendment introduces [DepositPreauth transactions](/docs/protocol-reference/transactions/transaction-types/depositpreauth) and [DepositPreauth ledger objects](/docs/protocol-reference/ledger-data/ledger-objects-types/deposit-pre-auth) to manage preauthorizations. + +##### Hooks + +Core amendment enabling Hook smart contract functionality on Xahau. _(Added by the [Hooks amendment][].)_ + +##### HooksUpdate1 + +Updates and improvements to the Hooks system. + +##### Remit + +Implements [XLS-55](https://github.com/XRPLF/XRPL-Standards/discussions/156). A new simple but powerful what-you-see-is-what-you-get push payment transaction type. Enables [Remit transactions](/docs/protocol-reference/transactions/transaction-types/remit) that allow paying multiple currencies and URITokens in the same transaction to the same destination. The transaction automatically pays to create missing trustlines, automatically pays the reserves on transferred tokens, and automatically pays to create the destination account if it doesn't exist. You can mint a receipt or bonus URIToken in-line within the transaction. Optionally inform a third party Hook about the transaction. No partial payments and no pathing. + +##### ZeroB2M + +Disables the burn-to-mint path for XRP to XAH. Normal behaviour of the Import transaction remains, but burned XRP is not credited. B2M is still available for key synchronisation or to activate an account, but cannot be used to mint new assets. + +##### Remarks + +The Remarks amendment allows key-value pairs (similar to hook state) to be stored by object owners on those objects. This is akin to flipping over a document and hand-writing a note on it. Remarks can be anything and mean different things to different parties. Remarks can also be set to immutable. Remarks follow an object through changes of ownership and can be used to achieve novel use cases like dynamic NFTs and simplify some otherwise very complicated hook state operations. Enables [SetRemarks transactions](/docs/protocol-reference/transactions/transaction-types/setremarks). + +##### Touch + +This amendment ensures all accounts involved in a transaction (all transactional stakeholders) are forced to appear in its metadata by incrementing a "touch counter" even if nothing else on the account was changed. This is named for the unix file utility touch. This provides better audit consistency and ease of programming automated tools. + +##### HookCanEmit + +This amendment adds a new field to HookSet objects: `HookCanEmit` is syntactically identical to the `HookOn` field, except that it controls which transaction types the Hook is allowed to emit rather than which transaction types trigger the hook. Note that it uses the same active-low semantics as `HookOn` with `SetHook` being active high. However if the field is absent it's taken to be that the Hook may emit any transaction including `SetHook`. Adds the `HookCanEmit` field to [HookDefinition](/docs/protocol-reference/ledger-data/ledger-objects-types/hook-definition) objects. + +##### Clawback + +Enables [Clawback transactions](/docs/protocol-reference/transactions/transaction-types/clawback) that allow issuers to revoke tokens that were previously issued by their account. This is a ported feature from the XRPL. _(Introduced in 2025.7.9-release+1951)_ + +##### DeepFreeze + +Enables deep freeze functionality for trustlines and assets. This is a ported feature from the XRPL. _(Introduced in 2025.7.9-release+1951)_ + +##### IOUIssuerWeakTSH + +Makes IOU issuers weak transactional stakeholders (TSH) in certain transaction types. Ensures that Currency Issuers have their hooks executed in third party transactions that touch or mention their currency, if they have opted into weak execution. See [Weak and Strong](/docs/hooks/concepts/weak-and-strong) for details. _(Introduced in 2025.7.9-release+1951)_ + +##### Cron + +Enables scheduled Hook execution via [CronSet transactions](/docs/protocol-reference/transactions/transaction-types/cronset) and [Cron ledger objects](/docs/protocol-reference/ledger-data/ledger-objects-types/cron). This feature allows Hooks to schedule a series of future self-invocations (akin to a cronjob in Linux systems) which can assist Hook developers in writing complex governance structures, games and more. The maximum number of repeats is 256, however issuing a further `CronSet` transaction can extend this once the number of repeats crosses a desired minimum threshold. _(Introduced in 2025.10.27-release+2405)_ + +##### ExtendedHookState + +Extends Hook state management capabilities, including the `HookStateScale` field for [AccountRoot](/docs/protocol-reference/ledger-data/ledger-objects-types/accountroot) objects to control when Hook state entries become stale. This feature expands the amount of data Hooks can store in their Hook State (key-value system for Hooks) to allow Hooks richer data storage when they need it. The scale (up to 16) affects both the maximum size of the value you may store in a single hook state, along with the number of reserve units that k-v pair consumes. A scale of 1 (default) means you pay 1 reserve for up-to 256 bytes stored per Hook State. A scale of 4 means you pay 4 reserve units for up-to 1024 bytes per Hook State. It's important to note that you pay this rate (the scale rate) even if all of your Hook States contain only a single byte. It is possible to increase the scale after your Hook already has stored state, but not to decrease it. Decreasing the scale requires all HookState to be first deleted. _(Introduced in 2025.10.27-release+2405)_ + +#### Bug Fix Amendments + +##### fixXahauV1 + +Enforces a namespaces per account limit of 256. Various bug fixes with URIToken logic. Ensures that default (0) STAmounts are recorded in metadata. Ensures that OfferID can be used instead of OfferSequence when cancelling an offer. Fixes a bug where certain hooks cannot be deleted. Fixes a bug where the quorum required for a `ttIMPORT` is accidentally too high. Allows accounts to appear more than once in a GenesisMint transaction. Changes the Issuer of a URIToken from strong to weak TSH when a URIToken is being burned. Ensures TSHes on escrows created by emitted transactions are correctly triggered. Adds hook parameters size fee to all txns (1 drop per byte). _(Introduced in 2024.9.11-release+985)_ + +##### fixXahauV2 + +Cleans up TSH logic and removes old redundant table. Adds informational flags to each member of `sfHookExecutions`, describing weak, strong etc. execution. Adds `sfEmitNonce` to each member of `sfHookEmissions`, so as to better disambiguate emitted txns. Additional sanity checks on emitted txns to ensure they are placed into the correct ledger. + +##### fixXahauV3 + +Further fixes for Xahau protocol implementation issues. This amendment ensures consistency and sensible outcomes for various edge cases. This amendment is set to default: _yes_ voting. If validators wish to vote against this amendment they must manually change their vote to no. _(Introduced in 2025.2.6-release+1299)_ + +##### fixNSDelete + +Fixes the behaviour of Hook State namespace deletion to ensure ledger consistency. Introduces a new tes code: `tesPARTIAL`. `tesPARTIAL` is returned if the transaction was successful but should be resubmitted by the user under a new sequence number to complete amortized work until `tesSUCCESS` is returned. + +##### fix240819 + +Bug fix amendment from August 19, 2024. + +##### fixPageCap + +Fixes issues related to page capacity limits. + +##### fix240911 + +Bug fix amendment from September 11, 2024. + +##### fixFloatDivide + +Fixes issues with floating point division operations in Hooks. This amendment ensures proper handling of division by zero and edge cases in the `float_divide` function. Changes the behaviour of the `float_divide` hook API to correct a small error. This amendment is set to default: _yes_ voting. See [float_divide](/docs/hooks/functions/float/float_divide) for details. _(Introduced in 2024.11.18-release+1141)_ + +##### fixReduceImport + +Fixes issues related to Import transaction processing. This amendment ensures consistency and sensible outcomes for various edge cases. This amendment is set to default: _yes_ voting. If validators wish to vote against this amendment they must manually change their vote to no. _(Introduced in 2025.2.6-release+1299)_ + +##### fix20250131 + +Bug fix amendment from January 31, 2025. This amendment ensures consistency and sensible outcomes for various edge cases. This amendment is set to default: _yes_ voting. If validators wish to vote against this amendment they must manually change their vote to no. _(Introduced in 2025.2.6-release+1299)_ + +##### fixRewardClaimFlags + +Fixes issues with reward claim transaction flags. + +##### fixProvisionalDoubleThreading + +Fixes issues with provisional double threading in transaction processing. Ensures the correct PreviousTxnID and transaction metadata are maintained in double threading scenarios. _(Introduced in 2025.7.9-release+1951)_ + +##### fixInvalidTxFlags + +Fixes a bug that currently allows invalid flags to be provided to some transactions. While these invalid flags currently do nothing, they should actually produce a malformed error. After this fix is applied, invalid flags will produce a malformed error as expected. _(Introduced in 2025.10.27-release+2405)_ + +##### fixCronStacking + +Fixes issues with Cron transaction stacking behavior. + +### Amendment Status + +For the most current status of amendments (enabled, voting, or vetoed), check the [xahaud repository](https://github.com/Xahau/xahaud) or query a running `xahaud` server using the `feature` command. diff --git a/src/content/docs/docs/features/developer-tooling/developer-tricks.mdx b/src/content/docs/docs/features/developer-tooling/developer-tricks.mdx index fb68899..23d51a5 100644 --- a/src/content/docs/docs/features/developer-tooling/developer-tricks.mdx +++ b/src/content/docs/docs/features/developer-tooling/developer-tricks.mdx @@ -9,4 +9,21 @@ Added: [https://github.com/Xahau/xahaud/pull/201](https://github.com/Xahau/xahau ## Server Definitions -Server definitions can eas +Server definitions can easily be fetched from public nodes. These definitions include binary codec information and other network-specific data needed for transaction serialization and deserialization. + +### Mainnet +- [`https://xahau.network/server_definitions.json`](https://xahau.network/server_definitions.json) + +### Testnet +- [`https://xahau-test.net/server_definitions.json`](https://xahau-test.net/server_definitions.json) + +### JSHooks-Testnet +- [`https://jshooks.xahau-test.net/server_definitions.json`](https://jshooks.xahau-test.net/server_definitions.json) + +These server definitions are essential for: +- Binary codec operations +- Transaction serialization +- Field type definitions +- Network-specific constants + +You can use these definitions in your applications to properly encode and decode transactions for the Xahau network. diff --git a/src/content/docs/docs/features/faucet-and-explorer.mdx b/src/content/docs/docs/features/faucet-and-explorer.mdx index 1492485..57fd61c 100644 --- a/src/content/docs/docs/features/faucet-and-explorer.mdx +++ b/src/content/docs/docs/features/faucet-and-explorer.mdx @@ -12,7 +12,7 @@ The Xahau Faucet & Explorers can be found here: JSON body with `destination` property: fund the mentioned `destination` account. * **Explorers:** * **Xahauexplorer:** [**https://test.xahauexplorer.com**](https://test.xahauexplorer.com) - * **XRPLF:** [**https://explorer.xahau-test.net**](https://explorer.xahau-test.net) + * **InFTF:** [**https://explorer.xahau-test.net**](https://explorer.xahau-test.net) * **XRPL.org:** [**https://xahau-testnet.xrpl.org**](https://xahau-testnet.xrpl.org) * **XRPLWin:** [**https://xahau-testnet.xrplwin.com**](https://xahau-testnet.xrplwin.com/) @@ -22,6 +22,6 @@ The Xahau Faucet & Explorers can be found here: * **Explorers:** * **Xahauexplorer:** [**https://xahauexplorer.com**](https://xahauexplorer.com/) * **Xahscan:** [**https://xahscan.com/**](https://xahscan.com/) - * **XRPLF:** [**https://explorer.xahau.network**](https://explorer.xahau.network/) + * **InFTF:** [**https://explorer.xahau.network**](https://explorer.xahau.network/) * **XRPL.org:** [**https://xahau.xrpl.org**](https://xahau.xrpl.org) * **XRPLWin:** [**https://xahau.xrplwin.com**](https://xahau.xrplwin.com/) diff --git a/src/content/docs/docs/features/transaction-signing/transaction-fees.mdx b/src/content/docs/docs/features/transaction-signing/transaction-fees.mdx index a3c4bbc..d1ca572 100644 --- a/src/content/docs/docs/features/transaction-signing/transaction-fees.mdx +++ b/src/content/docs/docs/features/transaction-signing/transaction-fees.mdx @@ -6,7 +6,7 @@ description: >- --- import { Aside } from '@astrojs/starlight/components'; -While libraries may deal with fee determination for you (see [.](./ "mention")), when building your own integrations with the Xahauy ledger, you may have to implement dynamic fee determination based on the transaction, source & destination account. +While libraries may deal with fee determination for you, when building your own integrations with the Xahau Network, you may have to implement dynamic fee determination based on the transaction, source & destination account. As the sender of a transaction will have to pay for the fees required for the invoked Hooks for the specific transaction type, where Hooks can live both on the source & destination account, you can send a TX Blob (signed with a dummy account) to the `fee` command, after which Xahau will return the specific fees required for the specific transaction. diff --git a/src/content/docs/docs/hooks/concepts/chaining.mdx b/src/content/docs/docs/hooks/concepts/chaining.mdx index b85660a..673c860 100644 --- a/src/content/docs/docs/hooks/concepts/chaining.mdx +++ b/src/content/docs/docs/hooks/concepts/chaining.mdx @@ -18,30 +18,30 @@ This was counter to the Hook Design Philosophy, so Hook Chaining was introduced. A Hook Chain is a sequence of up to **10** Hooks installed on an Xahau account. -* A Hook Chain executes successfully when every Hook in the chain has been individually executed and subsequently calls [accept](../technical/hooks-functions/control/accept.md). +* A Hook Chain executes successfully when every Hook in the chain has been individually executed and subsequently calls [accept](/docs/hooks/functions/control/accept). * Each chain's execution starts at chain position 0 and ends at chain position 9. If a position is blank (because it was never filled or because the hook that was installed there has been removed) then that position is skipped and treated as successful. * In order for a transaction to succeed, both ends of the transaction (sending side and receiving side) must have executed successfully. This means if there is a Hook Chain installed on both sides, then both Hook Chains must execute successfully for the transaction to succeed. -Hooks are installed into the chain using the [SetHook Transaction](sethook-transaction.md). When they are installed, the installer may specify install-time [Parameters](parameters.md) which may change the behaviour of the installed Hook. +Hooks are installed into the chain using the [SetHook Transaction](/docs/hooks/concepts/sethook-transaction). When they are installed, the installer may specify install-time [Parameters](/docs/hooks/concepts/parameters) which may change the behaviour of the installed Hook.
-![Example: Execution flow for a transaction passing through two Hook Chains](../../assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png) +![Example: Execution flow for a transaction passing through two Hook Chains](/assets/spaces_m6f29os4wP16vCS4lHNh_uploads_0OucxySTRinbe13SITJT_5561b32-sethook-Page-3.png)
*Example: Execution flow for a transaction passing through two Hook Chains*
### Chain Manipulation -In addition to the _install-time_ operations specified in the [SetHook Transaction](sethook-transaction.md), Hooks have some runtime control over chain execution: +In addition to the _install-time_ operations specified in the [SetHook Transaction](/docs/hooks/concepts/sethook-transaction), Hooks have some runtime control over chain execution: -* A Hook may determine its own `HookHash` by calling [hook_hash](../technical/hooks-functions/hook-context/hook_hash.md). -* A Hook may determine its location in the Hook Chain using [hook_pos](../technical/hooks-functions/hook-context/hook_pos.md). -* A Hook may skip (or re-enable) another Hook further down the chain using [hook_skip](../technical/hooks-functions/hook-context/hook_skip.md). -* A Hook may modify the [Parameters](parameters.md) of a Hook further down the chain using [hook_param_set](../technical/hooks-functions/hook-context/hook_param_set.md). +* A Hook may determine its own `HookHash` by calling [hook_hash](/docs/hooks/functions/hook-context/hook_hash). +* A Hook may determine its location in the Hook Chain using [hook_pos](/docs/hooks/functions/hook-context/hook_pos). +* A Hook may skip (or re-enable) another Hook further down the chain using [hook_skip](/docs/hooks/functions/hook-context/hook_skip). +* A Hook may modify the [Parameters](/docs/hooks/concepts/parameters) of a Hook further down the chain using [hook_param_set](/docs/hooks/functions/hook-context/hook_param_set). ### Weak Executions -Hook Chains are [Strongly Executed](weak-and-strong.md). However any Hook in any chain may flag that it requires a second, Weak Execution by calling [hook_again](../technical/hooks-functions/hook-context/hook_again.md). If all Hook Chains execute successfully then the originating transaction is applied. Once the originating transaction has been applied any Weak Executions may happen, in the following order: +Hook Chains are [Strongly Executed](/docs/hooks/concepts/weak-and-strong). However any Hook in any chain may flag that it requires a second, Weak Execution by calling [hook_again](/docs/hooks/functions/hook-context/hook_again). If all Hook Chains execute successfully then the originating transaction is applied. Once the originating transaction has been applied any Weak Executions may happen, in the following order: 1. `cbak` execution if this was an Emitted Transaction. -2. Weak Transactional Stake Holders who have opted in to allow a [Collect Call](collect-call.md). Execution order is first-come first-serve according to the event that caused the TSH to be flagged (such as pathing). +2. Weak Transactional Stake Holders who have opted in to allow a [Collect Call](/docs/hooks/concepts/collect-call). Execution order is first-come first-serve according to the event that caused the TSH to be flagged (such as pathing). 3. Any _Again as Weak_ (AAW) Hooks. Execution order for AAW is first numerically according to Account ID then numerically according to Hook position. diff --git a/src/content/docs/docs/hooks/concepts/collect-call.mdx b/src/content/docs/docs/hooks/concepts/collect-call.mdx index 8eb02d4..fa36ba2 100644 --- a/src/content/docs/docs/hooks/concepts/collect-call.mdx +++ b/src/content/docs/docs/hooks/concepts/collect-call.mdx @@ -18,7 +18,7 @@ Therefore during typical Weak execution the fee for the execution is collected f | Type of Weak Execution | Fee | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -|

Again As Weak
- Happens when a Strongly Executed Hook calls hook_again

| Free (already paid by the Strong Execution). | +|

Again As Weak
- Happens when a Strongly Executed Hook calls hook_again

| Free (already paid by the Strong Execution). | |

Callback
- Happens when an emitted transaction either makes it into a ledger or is flagged as being impossible to ever make it into a ledger.

| Free (already paid during Emission). | |

Weak Transactional Stakeholder
- Happens if a transaction in some way mildly affects your account.

| Paid for by your account (not by the originating transaction) if and only if both your account is marked with `asfTshCollect` flag and your Hook is marked with the `hsfCollect` flag. | diff --git a/src/content/docs/docs/hooks/concepts/compiling-hooks.mdx b/src/content/docs/docs/hooks/concepts/compiling-hooks.mdx index 1be8c21..4dc70e6 100644 --- a/src/content/docs/docs/hooks/concepts/compiling-hooks.mdx +++ b/src/content/docs/docs/hooks/concepts/compiling-hooks.mdx @@ -12,7 +12,7 @@ A Hook always implements and exports exactly one or both of the following functi `int64_t hook(uint32_t ctx) { ... }` _required_ * Executed whenever a transaction comes into or leaves from the account the Hook is set on (`ctx = 0`) or -* Executed when executed as a [Weak Transactional Stakeholder](weak-and-strong.md) (`ctx > 0`). +* Executed when executed as a [Weak Transactional Stakeholder](/docs/hooks/concepts/weak-and-strong) (`ctx > 0`). `int64_t cbak(uint32_t ctx) { ... }` _optional_ diff --git a/src/content/docs/docs/hooks/concepts/debugging-hooks.mdx b/src/content/docs/docs/hooks/concepts/debugging-hooks.mdx index e0fb909..e46b043 100644 --- a/src/content/docs/docs/hooks/concepts/debugging-hooks.mdx +++ b/src/content/docs/docs/hooks/concepts/debugging-hooks.mdx @@ -18,9 +18,9 @@ The following `trace` functions are available in the Hooks API | Hook API | What it does | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| [trace](../technical/hooks-functions/trace-debug/trace.md) | Print a utf-8 message, followed by a user-specified buffer (this last optionally as hex.) | -| [trace_num](../technical/hooks-functions/trace-debug/trace_num.md) | Print a utf-8 message, followed by an integer. | -| [trace_float](../technical/hooks-functions/trace-debug/trace_float.md) | Print a utf-8 message, followed by an XFL Floating point number. | +| [trace](/docs/hooks/functions/trace-debug/trace) | Print a utf-8 message, followed by a user-specified buffer (this last optionally as hex.) | +| [trace_num](/docs/hooks/functions/trace-debug/trace_num) | Print a utf-8 message, followed by an integer. | +| [trace_float](/docs/hooks/functions/trace-debug/trace_float) | Print a utf-8 message, followed by an XFL Floating point number. | ### Example diff --git a/src/content/docs/docs/hooks/concepts/emitted-transactions.mdx b/src/content/docs/docs/hooks/concepts/emitted-transactions.mdx index 2744c17..346d130 100644 --- a/src/content/docs/docs/hooks/concepts/emitted-transactions.mdx +++ b/src/content/docs/docs/hooks/concepts/emitted-transactions.mdx @@ -18,7 +18,7 @@ The solution: **Emitted Transactions**. We allow the Originating Transaction to Emitted Transactions are _new_ transactions created by the execution of a Hook and entered into consensus for processing in the next ledger. The transaction may be of any Transaction Type but must follow strict emission rules. -To emit a transaction the Hook first prepares the serialized transaction then calls [emit](../technical/hooks-functions/emitted-transaction/emit-1.md). +To emit a transaction the Hook first prepares the serialized transaction then calls [emit](/docs/hooks/functions/emitted-transaction/emit-1). Because emitted transactions can trigger Hooks in the next ledger which in turn may emit more transactions, all emitted transactions carry a `burden` and a `generation` field in their `EmitDetails` block. The `EmitDetails` block replaces the signature field in a traditional transaction. @@ -28,13 +28,13 @@ It is important to note that the Hooks API follows the strict rule of _no rewrit ### Callbacks -As introduced in [Introduction and Terminology](terminology.md) emitted transactions trigger callbacks when they are accepted into a ledger. Due to the decentralised nature of consensus acceptance into a ledger of an emitted transaction is **not a guarantee**, although it is usually all-but guaranteed. +As introduced in [Introduction and Terminology](/docs/hooks/concepts/terminology) emitted transactions trigger callbacks when they are accepted into a ledger. Due to the decentralised nature of consensus acceptance into a ledger of an emitted transaction is **not a guarantee**, although it is usually all-but guaranteed. If an emitted transaction expires before it can be accepted into a ledger (for any number of reasons: the ledgers may be full, the fee may be too high for the emitted transaction or the emitted transaction may be somehow invalid) then a _pseudo transaction_ is created in the ledger to clean up the emitted transaction. This pseudo transaction also calls the callback of your hook, with `parameter = 1` to indicate the emitted transaction indeed failed. ### Emission Rules -The [emit](../technical/hooks-functions/emitted-transaction/emit-1.md) Hook API will enforce the following rules on a proposed (to be emitted) transaction. +The [emit](/docs/hooks/functions/emitted-transaction/emit-1) Hook API will enforce the following rules on a proposed (to be emitted) transaction. | # | Emission Rule | Explanation | | - | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -53,10 +53,10 @@ All emitted transactions must contain an `sfEmitDetails` object correctly popula | Field | Required Value | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| sfEmitGeneration |

If the Originating Transaction was itself an emitted transaction then one more than the sfEmitGeneration of that transaction.

If the Originating Transaction was not an emitted transaction then 1.

This should be populated using etxn_generation.

| This field keeps track of a chain of emitted transactions that in turn cause other transactions to be emitted. | -| sfEmitBurden |

If the Originating Transaction was itself an emitted transaction then the burden of the Originating Transaction multiplied by the maximum number of transactions the Hook has declared it will emit using etxn_reserve.

If the Originating Transaction was not an emitted transaction then 1.

This should be populated using etxn_burden.

| This field is a heuristic for detecting forkbombs. Fees are based on burden and will increase exponentially when a chain reaction is started to prevent the network becoming overun by self-reinforcing emitted transactions. | +| sfEmitGeneration |

If the Originating Transaction was itself an emitted transaction then one more than the sfEmitGeneration of that transaction.

If the Originating Transaction was not an emitted transaction then 1.

This should be populated using etxn_generation.

| This field keeps track of a chain of emitted transactions that in turn cause other transactions to be emitted. | +| sfEmitBurden |

If the Originating Transaction was itself an emitted transaction then the burden of the Originating Transaction multiplied by the maximum number of transactions the Hook has declared it will emit using etxn_reserve.

If the Originating Transaction was not an emitted transaction then 1.

This should be populated using etxn_burden.

| This field is a heuristic for detecting forkbombs. Fees are based on burden and will increase exponentially when a chain reaction is started to prevent the network becoming overun by self-reinforcing emitted transactions. | | sfEmitParentTxnID | The transaction ID of the Originating Transaction | The Hook Execution that emitted the transaction is connected to the Originating Transaction. Therefore this field is always required for the efficient tracing of behaviour. | -| sfEmitNonce | A special deterministic nonce produced by a call to [nonce](../technical/hooks-functions/emitted-transaction/etxn_nonce.md) | Emitted Transactions would be identical with the same fields and therefore have identical transaction hashes if a nonce were not used. However every node on the network needs to agree on the nonce, so a special Hook API to produce a deterministic nonce is made available. | +| sfEmitNonce | A special deterministic nonce produced by a call to [nonce](/docs/hooks/functions/emitted-transaction/etxn_nonce) | Emitted Transactions would be identical with the same fields and therefore have identical transaction hashes if a nonce were not used. However every node on the network needs to agree on the nonce, so a special Hook API to produce a deterministic nonce is made available. | | sfEmitCallback | The 20 byte Hook Account ID | This field is used by xahaud when it needs to intitate a callback, such that it knows which Hook and account to initate the callback on. Callbacks happen when an emitted transaction is accepted into a ledger. |