Skip to content

Commit fbc68e3

Browse files
SilkjaerSilkjaer
authored
Merge pull request #71 from Ekiserrepe/main
Create cronset page
2 parents 9fcb9f2 + b9a9984 commit fbc68e3

1 file changed

Lines changed: 101 additions & 0 deletions

File tree

  • src/content/docs/docs/protocol-reference/transactions/transaction-types

‎src/content/docs/docs/protocol-reference/transactions/transaction-types/cronset.mdx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: CronSet
3+
description: >-
4+
A CronSet transaction enables Hooks to schedule recurring self-invocations at
5+
regular intervals, similar to Linux cronjobs. This facilitates complex
6+
governance structures and automated processes within Hook frameworks.
7+
---
8+
\[[Source](https://github.com/Xahau/xahaud/blob/dev/src/ripple/app/tx/impl/CronSet.cpp)]
9+
10+
_(Added by the CronSet amendment.)_
11+
12+
### Example
13+
14+
```json
15+
{
16+
"TransactionType": "CronSet",
17+
"Account": "rYourAccountAddress",
18+
"StartTime": 816348759,
19+
"RepeatCount": 3,
20+
"DelaySeconds": 120
21+
}
22+
```
23+
24+
| Field | JSON Type | \[Internal Type]\[] | Description |
25+
| -------------- | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26+
| `Account` | String | AccountID | The Hook account initiating the cron. This is the account that will be invoked when the cron executes. |
27+
| `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. |
28+
| `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. |
29+
| `DelaySeconds` | Number | UInt32 | _(Optional)_ Time interval in seconds between each execution. Omit when deleting a cron. |
30+
31+
### How CronSet Works
32+
33+
CronSet transactions enable scheduled, automated Hook execution on the Xahau blockchain at regular intervals, eliminating the need for external services or manual triggers.
34+
35+
The workflow involves four key steps:
36+
37+
1. Install a Hook with the `hsfCOLLECT` flag enabled
38+
2. Enable Transaction Signature Hook Collection `asfTshCollect` on your account (SetFlag: 11)
39+
3. Create a CronSet transaction with scheduling parameters
40+
4. Let Xahau handle automatic execution
41+
42+
### Execution Mechanism
43+
44+
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.
45+
46+
The scheduled Hook will be invoked automatically at the specified intervals without requiring external triggers.
47+
48+
### Time Format
49+
50+
Xahau uses Ripple Epoch time (seconds since January 1, 2000), not Unix time. To convert from JavaScript Date:
51+
52+
```javascript
53+
const rippleEpochTime = Math.floor(Date.now() / 1000) - 946684800;
54+
```
55+
56+
### Deleting a Cron
57+
58+
To remove an existing Cron, omit `StartTime`, `RepeatCount`, and `DelaySeconds` while setting `Flags: 1` (tfCronUnset):
59+
60+
```json
61+
{
62+
"TransactionType": "CronSet",
63+
"Account": "rYourAccountAddress",
64+
"Flags": 1
65+
}
66+
```
67+
68+
### Extending Repeat Count
69+
70+
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`.
71+
72+
### CronSet Flags
73+
74+
Transactions of the CronSet type support additional values in the `Flags` field, as follows:
75+
76+
| Flag Name | Hex Value | Decimal Value | Description |
77+
| ------------- | ------------ | ------------- | -------------------------------------------------------------------------------- |
78+
| `tfCronUnset` | `0x00000001` | 1 | Removes an existing Cron. All scheduling fields must be omitted when this is set. |
79+
80+
### Limitations and Constraints
81+
82+
- CronSet cannot currently be delegated to another account
83+
- Hooks must self-emit CronSet transactions or operate under joint management arrangements
84+
- `RepeatCount`: Must be greater than 0 and cannot exceed 256 per transaction (extendable via subsequent transactions)
85+
- `DelaySeconds`: Maximum of 31,536,000 seconds (365 days)
86+
- `StartTime`: Must be current time or future; cannot exceed 365 days ahead
87+
- Cannot combine `tfCronUnset` flag with `DelaySeconds`, `RepeatCount`, or `StartTime` fields
88+
- When creating a cron, `DelaySeconds` and `RepeatCount` must both exist or both be absent
89+
90+
### Error Cases
91+
92+
Besides errors that can occur for all transactions, CronSet transactions can result in the following transaction result codes:
93+
94+
| Error Code | Description |
95+
| ------------------ | -------------------------------------------------------------------------------------------------- |
96+
| `temDISABLED` | Occurs if the Cron feature is not enabled. |
97+
| `temINVALID_FLAG` | Occurs if invalid flags are set in the transaction. |
98+
| `temMALFORMED` | Occurs if the transaction is malformed with invalid field combinations. |
99+
| `tecEXPIRED` | Occurs if `StartTime` is in the past or more than 365 days in the future. |
100+
| `tefINTERNAL` | Occurs if the account ledger entry is missing. |
101+
| `tefBAD_LEDGER` | Occurs if the Cron object is missing, points to a non-cron entry, or owner directory removal fails. |

0 commit comments

Comments
 (0)