From 334cfc3e3181a50544d43bb177da65236e588b66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ekiserrep=C3=A9?= Date: Wed, 12 Nov 2025 16:55:51 +0100 Subject: [PATCH 01/22] Update connect.mdx --- src/pages/connect.mdx | 76 +++++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 39 deletions(-) diff --git a/src/pages/connect.mdx b/src/pages/connect.mdx index 0b1314c..f0d15b9 100644 --- a/src/pages/connect.mdx +++ b/src/pages/connect.mdx @@ -7,6 +7,37 @@ import PageSection from '../components/PageSection.astro'; +## Upcoming Events + +### Next Event: Blockchain and Regulation: Europe Under Legal Scrutiny + +
+
+ 📅 Date & Time: Thursday, December 4th, 2025 at 6:30 PM (18:30) CET +
+
+ 📍 Location: MIL (Madrid Innovation Lab)
+ Calle Bravo Murillo 37-39
+ Madrid, Spain
+ View on Google Maps +
+
+ 🎤 Featured Speakers: +
+
• Horacio Gómez Rey – Head of Legal Spain, N26
+
• Pedro Méndez de Vigo – AVP Legal Europe, Crypto.com
+
+
+
+ 📺 Live Stream: Watch online at Madrid Innovation Lab YouTube +
+
+ 🎟️ Registration: Register to attend in person using this [form](https://forms.office.com/e/3vrU9ihHVe) +
+
+ +Join us for an in-depth discussion on blockchain regulation in Europe, featuring leading legal experts from major fintech and crypto companies. This session will explore the evolving regulatory landscape, compliance challenges, and the future of blockchain under European legal scrutiny. + ## About Xahau Connect **Xahau Connect** is a series of professional blockchain events created by [**INFTF**](https://www.inftf.org) (Inclusive Financial Technology Foundation) to foster serious, agnostic discussions about blockchain technology and its real-world applications. @@ -40,36 +71,16 @@ Xahau Connect events are designed for: -## Upcoming Events +## Speakers, Sponsors & Contact -### Next Event: Blockchain and Regulation: Europe Under Legal Scrutiny +### Get Involved -
-
- 📅 Date & Time: Thursday, December 4th, 2025 at 6:30 PM (18:30) CET -
-
- 📍 Location: MIL (Madrid Innovation Lab)
- Calle Bravo Murillo 37-39
- Madrid, Spain
- View on Google Maps -
-
- 🎤 Featured Speakers: -
-
• Horacio Gómez Rey – Head of Legal Spain, N26
-
• Pedro Méndez de Vigo – AVP Legal Europe, Crypto.com
-
-
-
- 📺 Live Stream: Watch online at Madrid Innovation Lab YouTube -
-
- 🎟️ Registration: Register to attend in person using this [form](https://forms.office.com/e/3vrU9ihHVe) -
+
+
• Speaking Proposals & Sponsorship Inquiries: connect@xahau.org
-Join us for an in-depth discussion on blockchain regulation in Europe, featuring leading legal experts from major fintech and crypto companies. This session will explore the evolving regulatory landscape, compliance challenges, and the future of blockchain under European legal scrutiny. +We're grateful to our partners who support Xahau Connect's mission of fostering professional blockchain discourse. Partner and speaker details will be announced as we confirm participation for upcoming events. + ### Subscribe for Updates @@ -80,17 +91,4 @@ To receive notifications about upcoming Xahau Connect events:
• Email us at connect@xahau.org
 - - -## Speakers, Sponsors & Contact - -### Get Involved - -
-
• Speaking Proposals & Sponsorship Inquiries: connect@xahau.org
-
- -We're grateful to our partners who support Xahau Connect's mission of fostering professional blockchain discourse. Partner and speaker details will be announced as we confirm participation for upcoming events. - - From b9a9984f8626ff277cc9735b2937232b9d9c934d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ekiserrep=C3=A9?= Date: Mon, 17 Nov 2025 07:08:07 +0100 Subject: [PATCH 02/22] Create cronset.mdx --- .../transaction-types/cronset.mdx | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 src/content/docs/docs/protocol-reference/transactions/transaction-types/cronset.mdx diff --git a/src/content/docs/docs/protocol-reference/transactions/transaction-types/cronset.mdx b/src/content/docs/docs/protocol-reference/transactions/transaction-types/cronset.mdx new file mode 100644 index 0000000..ed969e7 --- /dev/null +++ b/src/content/docs/docs/protocol-reference/transactions/transaction-types/cronset.mdx @@ -0,0 +1,101 @@ +--- +title: CronSet +description: >- + A CronSet transaction enables Hooks to schedule recurring self-invocations at + regular intervals, similar to Linux cronjobs. This facilitates complex + governance structures and automated processes within Hook frameworks. +--- +\[[Source](https://github.com/Xahau/xahaud/blob/dev/src/ripple/app/tx/impl/CronSet.cpp)] + +_(Added by the CronSet amendment.)_ + +### Example + +```json +{ + "TransactionType": "CronSet", + "Account": "rYourAccountAddress", + "StartTime": 816348759, + "RepeatCount": 3, + "DelaySeconds": 120 +} +``` + +| Field | JSON Type | \[Internal Type]\[] | Description | +| -------------- | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Account` | String | AccountID | The Hook account initiating the cron. This is the account that will be invoked when the cron executes. | +| `StartTime` | Number | UInt32 | _(Optional)_ Ripple Epoch timestamp when the first execution should occur. Use `0` for immediate execution. If omitted when deleting a cron, the transaction removes the cron. | +| `RepeatCount` | Number | UInt32 | _(Optional)_ Number of times the cron should execute (maximum 256 per transaction). Can be extended via subsequent CronSet transactions. Omit when deleting a cron. | +| `DelaySeconds` | Number | UInt32 | _(Optional)_ Time interval in seconds between each execution. Omit when deleting a cron. | + +### How CronSet Works + +CronSet transactions enable scheduled, automated Hook execution on the Xahau blockchain at regular intervals, eliminating the need for external services or manual triggers. + +The workflow involves four key steps: + +1. Install a Hook with the `hsfCOLLECT` flag enabled +2. Enable Transaction Signature Hook Collection `asfTshCollect` on your account (SetFlag: 11) +3. Create a CronSet transaction with scheduling parameters +4. Let Xahau handle automatic execution + +### Execution Mechanism + +When a cron is ready to execute, the Cron engine inserts a pseudo-transaction of type `Cron` into the ledger, containing an `Owner` field referencing the originating Hook account. Hook developers must enable collect calls, as the Owner constitutes a weak transactional stakeholder. + +The scheduled Hook will be invoked automatically at the specified intervals without requiring external triggers. + +### Time Format + +Xahau uses Ripple Epoch time (seconds since January 1, 2000), not Unix time. To convert from JavaScript Date: + +```javascript +const rippleEpochTime = Math.floor(Date.now() / 1000) - 946684800; +``` + +### Deleting a Cron + +To remove an existing Cron, omit `StartTime`, `RepeatCount`, and `DelaySeconds` while setting `Flags: 1` (tfCronUnset): + +```json +{ + "TransactionType": "CronSet", + "Account": "rYourAccountAddress", + "Flags": 1 +} +``` + +### Extending Repeat Count + +Upon reaching a minimum threshold, a subsequent CronSet transaction can extend the repeat count beyond the initial 256 execution limit by submitting a new CronSet transaction with an updated `RepeatCount`. + +### CronSet Flags + +Transactions of the CronSet type support additional values in the `Flags` field, as follows: + +| Flag Name | Hex Value | Decimal Value | Description | +| ------------- | ------------ | ------------- | -------------------------------------------------------------------------------- | +| `tfCronUnset` | `0x00000001` | 1 | Removes an existing Cron. All scheduling fields must be omitted when this is set. | + +### Limitations and Constraints + +- CronSet cannot currently be delegated to another account +- Hooks must self-emit CronSet transactions or operate under joint management arrangements +- `RepeatCount`: Must be greater than 0 and cannot exceed 256 per transaction (extendable via subsequent transactions) +- `DelaySeconds`: Maximum of 31,536,000 seconds (365 days) +- `StartTime`: Must be current time or future; cannot exceed 365 days ahead +- Cannot combine `tfCronUnset` flag with `DelaySeconds`, `RepeatCount`, or `StartTime` fields +- When creating a cron, `DelaySeconds` and `RepeatCount` must both exist or both be absent + +### Error Cases + +Besides errors that can occur for all transactions, CronSet transactions can result in the following transaction result codes: + +| Error Code | Description | +| ------------------ | -------------------------------------------------------------------------------------------------- | +| `temDISABLED` | Occurs if the Cron feature is not enabled. | +| `temINVALID_FLAG` | Occurs if invalid flags are set in the transaction. | +| `temMALFORMED` | Occurs if the transaction is malformed with invalid field combinations. | +| `tecEXPIRED` | Occurs if `StartTime` is in the past or more than 365 days in the future. | +| `tefINTERNAL` | Occurs if the account ledger entry is missing. | +| `tefBAD_LEDGER` | Occurs if the Cron object is missing, points to a non-cron entry, or owner directory removal fails. | From 873468d8faab9bd7a2a728cebb7e7765c14ceaf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Silkj=C3=A6r?= Date: Mon, 17 Nov 2025 15:23:33 +0100 Subject: [PATCH 03/22] Update documentation links and content across various sections, including hooks, transactions, and infrastructure. Fix broken links, enhance clarity, and add new information on amendment status and developer tooling features. --- src/content/docs/docs/features/amendments.mdx | 66 +++++++++++++++++++ .../developer-tooling/developer-tricks.mdx | 19 +++++- .../transaction-signing/transaction-fees.mdx | 2 +- .../docs/docs/hooks/concepts/chaining.mdx | 20 +++--- .../docs/docs/hooks/concepts/collect-call.mdx | 2 +- .../docs/hooks/concepts/compiling-hooks.mdx | 8 +-- .../docs/hooks/concepts/debugging-hooks.mdx | 6 +- .../hooks/concepts/emitted-transactions.mdx | 12 ++-- .../hooks/concepts/execution-metadata.mdx | 4 +- .../concepts/floating-point-numbers-xfl.mdx | 36 +++++----- .../docs/docs/hooks/concepts/grants.mdx | 11 ++-- .../docs/docs/hooks/concepts/hook-fees.mdx | 6 +- .../docs/docs/hooks/concepts/hookon-field.mdx | 2 +- .../concepts/introduction/example-usage.mdx | 10 +-- .../hooks/concepts/introduction/index.mdx | 8 +-- .../hooks/concepts/loops-and-guarding.mdx | 6 +- .../docs/docs/hooks/concepts/namespaces.mdx | 14 ++-- .../docs/docs/hooks/concepts/parameters.mdx | 14 ++-- .../reference-counted-hook-definitions.mdx | 4 +- .../hooks/concepts/serialized-objects.mdx | 18 ++--- .../hooks/concepts/sethook-transaction.mdx | 12 ++-- .../docs/hooks/concepts/slots-and-keylets.mdx | 24 +++---- .../docs/hooks/concepts/state-management.mdx | 12 ++-- .../docs/docs/hooks/concepts/terminology.mdx | 20 +++--- .../docs/hooks/concepts/weak-and-strong.mdx | 8 +-- .../docs/hooks/functions/control/accept.mdx | 2 +- .../docs/hooks/functions/control/rollback.mdx | 2 +- .../functions/emitted-transaction/emit.mdx | 4 +- .../emitted-transaction/etxn_fee_base.mdx | 4 +- .../docs/hooks/functions/float/float_int.mdx | 2 +- .../docs/hooks/functions/float/float_sto.mdx | 12 ++-- .../hooks/functions/float/float_sto_set.mdx | 2 +- .../functions/hook-context/hook_again.mdx | 4 +- .../functions/hook-context/hook_hash.mdx | 2 +- .../functions/hook-context/hook_param.mdx | 2 +- .../functions/hook-context/hook_param_set.mdx | 8 +-- .../hooks/functions/hook-context/hook_pos.mdx | 2 +- .../hooks/functions/ledger/ledger_keylet.mdx | 2 +- .../originating-transaction/meta_slot.mdx | 4 +- .../originating-transaction/otxn_param.mdx | 2 +- .../overview/hook-api-conventions.mdx | 8 +-- .../hooks/functions/overview/return-codes.mdx | 2 +- .../functions/serialization/sto_emplace.mdx | 4 +- .../functions/serialization/sto_erase.mdx | 4 +- .../functions/serialization/sto_subarray.mdx | 8 +-- .../functions/serialization/sto_subfield.mdx | 8 +-- .../functions/serialization/sto_validate.mdx | 4 +- .../docs/hooks/functions/slot/slot_float.mdx | 4 +- .../docs/hooks/functions/slot/slot_set.mdx | 2 +- .../docs/docs/hooks/functions/state/state.mdx | 8 +-- .../hooks/functions/state/state_foreign.mdx | 6 +- .../functions/state/state_foreign_set.mdx | 8 +-- .../docs/hooks/functions/state/state_set.mdx | 10 +-- .../hooks/functions/trace-debug/trace.mdx | 4 +- .../functions/trace-debug/trace_float.mdx | 2 +- .../hooks/functions/trace-debug/trace_num.mdx | 2 +- .../hooks/functions/utilities/util_accid.mdx | 2 +- .../hooks/functions/utilities/util_keylet.mdx | 2 +- .../hooks/functions/utilities/util_raddr.mdx | 2 +- .../functions/utilities/util_sha512h.mdx | 2 +- src/content/docs/docs/hooks/index.mdx | 4 +- .../infrastructure/advanced-configuration.mdx | 4 +- .../infrastructure/enabling-validation.mdx | 10 +-- .../docs/docs/infrastructure/identity.mdx | 4 +- .../docs/infrastructure/installing-xahaud.mdx | 2 +- .../docs/docs/infrastructure/interacting.mdx | 23 ++++++- .../infrastructure/system-requirements.mdx | 2 +- .../protocol-reference/ledger-data/index.mdx | 21 ++++-- .../ledger-objects-types/accountroot.mdx | 6 +- .../ledger-data/ledger-objects-types/cron.mdx | 57 ++++++++++++++++ .../pseudo-transaction-types/cron.mdx | 59 +++++++++++++++++ .../transaction-types/accountset.mdx | 6 +- .../transaction-types/checkcash.mdx | 2 +- .../transaction-types/checkcreate.mdx | 2 +- .../transaction-types/escrowcreate.mdx | 2 +- .../transactions/transaction-types/invoke.mdx | 26 +++++--- .../transaction-types/offercreate.mdx | 8 +-- .../transaction-types/payment.mdx | 4 +- .../transaction-types/paymentchannelclaim.mdx | 4 +- .../paymentchannelcreate.mdx | 2 +- .../transaction-types/paymentchannelfund.mdx | 2 +- .../transactions/transaction-types/remit.mdx | 2 +- .../transaction-types/sethook.mdx | 2 +- .../transaction-types/uritokenbuy.mdx | 2 +- .../uritokencreateselloffer.mdx | 2 +- .../transaction-types/uritokenmint.mdx | 2 +- src/content/docs/docs/what-is-different.mdx | 22 +++---- src/content/references/global.md | 23 +++++++ src/content/references/pseudo-transactions.md | 1 + src/content/references/transactions.md | 2 +- src/pages/contest.mdx | 2 +- 91 files changed, 534 insertions(+), 266 deletions(-) create mode 100644 src/content/docs/docs/protocol-reference/ledger-data/ledger-objects-types/cron.mdx create mode 100644 src/content/docs/docs/protocol-reference/transactions/pseudo-transaction-types/cron.mdx diff --git a/src/content/docs/docs/features/amendments.mdx b/src/content/docs/docs/features/amendments.mdx index db7cf5b..1c587d5 100644 --- a/src/content/docs/docs/features/amendments.mdx +++ b/src/content/docs/docs/features/amendments.mdx @@ -54,3 +54,69 @@ 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). + +**Hooks** - Core amendment enabling Hook smart contract functionality on Xahau. _(Added by the [Hooks amendment][].)_ + +**HooksUpdate1** - Updates and improvements to the Hooks system. + +**Remit** - Enables [Remit transactions](/docs/protocol-reference/transactions/transaction-types/remit) that allow sending multiple payment types, minting URITokens, transferring URITokens, and activating accounts in a single transaction. + +**ZeroB2M** - Enables Burn2Mint operations with zero amounts. Fixes issues related to Burn2Mint operations when dealing with zero amounts. + +**Remarks** - Enables [SetRemarks transactions](/docs/protocol-reference/transactions/transaction-types/setremarks) that allow accounts to attach, update, or remove arbitrary remarks (key-value pairs) on supported ledger objects. + +**Touch** - Enables Touch transactions for account activation and interaction. + +**HookCanEmit** - Adds the `HookCanEmit` field to [HookDefinition](/docs/protocol-reference/ledger-data/ledger-objects-types/hook-definition) objects, specifying which transaction types a hook is allowed to emit. + +**Clawback** - Enables [Clawback transactions](/docs/protocol-reference/transactions/transaction-types/clawback) that allow issuers to revoke tokens that were previously issued by their account. + +**DeepFreeze** - Enables deep freeze functionality for trustlines and assets. + +**IOUIssuerWeakTSH** - Makes IOU issuers weak transactional stakeholders (TSH) in certain transaction types. See [Weak and Strong](/docs/hooks/concepts/weak-and-strong) for details. + +**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). _(Added by the [CronSet amendment][].)_ + +**ExtendedHookState** - Extends Hook state management capabilities, including the `HookStaleScale` field for [AccountRoot](/docs/protocol-reference/ledger-data/ledger-objects-types/accountroot) objects to control when Hook state entries become stale. _(Added by the [ExtendedHookState amendment][].)_ + +#### Bug Fix Amendments + +**fixXahauV1** - Fixes issues in the Xahau protocol implementation. _(Introduced in 2024.9.11-release+985)_ + +**fixXahauV2** - Additional fixes for Xahau protocol implementation issues. + +**fixXahauV3** - Further fixes for Xahau protocol implementation issues. + +**fixNSDelete** - Fixes issues related to namespace deletion operations in Hooks. + +**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. See [float_divide](/docs/hooks/functions/float/float_divide) for details. + +**fixReduceImport** - Fixes issues related to Import transaction processing. + +**fix20250131** - Bug fix amendment from January 31, 2025. + +**fixRewardClaimFlags** - Fixes issues with reward claim transaction flags. + +**fixProvisionalDoubleThreading** - Fixes issues with provisional double threading in transaction processing. + +**fixInvalidTxFlags** - Fixes issues with invalid transaction flags. + +**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/transaction-signing/transaction-fees.mdx b/src/content/docs/docs/features/transaction-signing/transaction-fees.mdx index a3c4bbc..a5998c4 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 ledger, 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..21aaddb 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]sethook-transaction. When they are installed, the installer may specify install-time [Parameters]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](/docs/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]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]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]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]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..f31d6ad 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]weak-and-strong (`ctx > 0`). `int64_t cbak(uint32_t ctx) { ... }` _optional_ @@ -29,7 +29,7 @@ Here is an example Hook written in C. The Hook prints 0...3 to the trace log bef ```c #include -#define GUARD(maxiter) _g(__LINE__, (maxiter)+1) +#define GUARDmaxiter _g(__LINE__, maxiter+1) extern int32_t _g (uint32_t id, uint32_t maxiter); extern int64_t accept (uint32_t read_ptr, uint32_t read_len, int64_t error_code); extern int64_t trace_num (uint32_t read_ptr, uint32_t read_len, int64_t number); @@ -57,7 +57,7 @@ A [variety of compilers](https://www.google.com/search?q=webassembly+compiler+C) (module (type (;0;) (func (param i32 i32) (result i32))) (type (;1;) (func (param i32 i32 i64) (result i64))) - (type (;2;) (func)) + (type (;2;) func) (type (;3;) (func (param i32) (result i64))) (import "env" "_g" (func $_g (type 0))) (import "env" "trace_num" (func $trace_num (type 1))) @@ -208,7 +208,7 @@ Above we can see: * Three functions are imported from the Hooks API (`_g`, `accept`, `trace_num`) * Two functions are defined by the hook (`cbak`, `hook`) * Two functions are exported by the hook (again: `cbak`, `hook`) -* Some static (constant) data is recorded in the hook (see `data` at the bottom). +* Some static constant data is recorded in the hook (see `data` at the bottom). It is very important to note that a Hook _must only_ import functions available to it from the Hooks API and _must_ only export the `cbak` and `hook` functions. In additional all hooks must import `_g` from the Hooks API, which is the `guard` function. 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..47dd415 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]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. |