Entities
Every entity OpenTrigger writes, with its attributes, payload and lifetime.
The format's rules:
- Searchable fields are attributes; everything else is a JSON payload. Attribute names are lowercase
(the node rejects uppercase), so the block to fire at is
fireat. - Every compared number is a
u64. A bare number is ani32and silently never matches au64range. - Addresses and keys in attributes are lowercase hex, so equality matches however callers wrote them.
- Every entity has
typeandv(format version,i32, currently1). - Who wrote it is Arkiv's
$creator, never an attribute.
type | Written by | Lifetime |
|---|---|---|
trg.rule | The rule's creator | Until its deadline + 7 days, at least 1 day |
trg.claim | A worker | 60 seconds (30 blocks) |
trg.receipt | A worker | 30 days |
trg.worker | A worker | 5 minutes, renewed every minute |
trg.rule
| Attribute | Type | Notes |
|---|---|---|
type, v | str, i32 | trg.rule, 1 |
app | str | Lets an app find only its own rules (default arkiv-triggers) |
on | str | expire or block |
target | str | expire only: the entity whose expiry fires the rule |
fireat | u64 | block only: the block that fires it |
offset | u64 | Fire this many blocks early; 0 is on time |
action | str | telegram, webhook, receipt, extend |
worker | str | any or one worker's address |
repeat | str | once (the only value in v1) |
Payload: { name, message, chat, url, extendDays, retries }, each when relevant.
trg.claim
| Attribute | Type | Notes |
|---|---|---|
type, v | str, i32 | trg.claim, 1 |
rule | str | The rule's key |
worker | str | The claiming worker (also its $creator) |
deadline | u64 | The deadline being claimed |
No payload. The earliest $createdAt wins; ties go to the lowest entity key.
trg.receipt
| Attribute | Type | Notes |
|---|---|---|
type, v | str, i32 | trg.receipt, 1 |
rule | str | The rule's key |
rulecreator | str | The rule's $creator |
action | str | The action that ran |
status | str | ok, failed or skipped |
deadline | u64 | The block the rule was due |
firedat | u64 | The block it fired |
Payload: { "reason": "target expired", "result": { "code": 200, "latencyMs": 412, "attempts": 1 } }.
result may hold code, messageId, newExpiresAt, error, latencyMs, attempts.
trg.worker
| Attribute | Type | Notes |
|---|---|---|
type, v | str, i32 | trg.worker, 1 |
version | str | arkiv-triggers/0.1.1 |
mode | str | any or own |
lastblock | u64 | Last block fully processed |
actions | str | Comma-separated actions it can run |
operator | str | Optional: the owner's main wallet |
Payload: { "sealKey": "0x…", "operatorSig": "0x…" }.
Queries
| Who | Purpose | Query |
|---|---|---|
| Worker | Rules it might fire | type = "trg.rule" |
| Worker | Live claims | type = "trg.claim" |
| Worker, SDK | Receipts since a block | type = "trg.receipt" && firedat >= u64(n) |
| SDK | My rules | type = "trg.rule", created by me |
| SDK | Receipts for my rules | type = "trg.receipt" && rulecreator = "0x…" |
| SDK | One rule's receipts and claims | type = … && rule = "0x…" |
| SDK, dashboard | Workers | type = "trg.worker" (optionally && operator = "0x…") |
Queries page 200 at a time, pinned to one block so a page cursor stays valid.