Add and Read Records
This guide shows how to append records to an existing AuditTrail object, read them back by sequence number, and paginate through the full record history.
Prerequisites
- An existing
AuditTrailobject on the IOTA network - A capability with
AddRecordpermission (e.g., aRecordAdminrole) - Familiarity with creating an
AuditTrailobject
Steps
1. Set Up Multiple Wallets
Create an admin wallet to set up the trail and a record-admin wallet that adds and reads records.
Used Utility Functions
In this example we expect the record-admin address to already own a capability granting the AddRecord permission
and the admin address to own full admin permissions as been shown in the Create an Audit Trail
how-to page.
2. Add Records
Each record contains data (text or binary) and optional metadata (a string describing the event context). Records are appended sequentially and each receives an auto-incrementing sequence number.
3. Read Records by Sequence Number
Fetch individual records using their sequence number. Sequence numbers start at 0 (the initial seed record).
4. Query Record Count
Check how many records currently exist in the trail.
5. Paginate Through Records
Use cursor-based pagination to traverse large trails efficiently. Each page returns a batch of records, a cursor for the next page, and a flag indicating whether more pages exist.
Expected Behavior
- Records are appended with auto-incrementing sequence numbers starting after the initial seed record.
- Individual records can be fetched by sequence number.
- Paginated listing supports configurable page sizes (max 1000 per page).
- The
has_next_page/hasNextPageflag and cursor enable full traversal.
Running Examples Locally
In order to run the examples, you will need to run an IOTA network locally. See the local network setup guide.
Full Example Code
- Rust
- Typescript (Node.js)
loading...
loading...