Access Read-Only Methods on an Audit Trail
Access Read-Only Methods
This guide demonstrates how to use the available read-only methods to inspect and query an AuditTrail object. These methods provide comprehensive information about trail state, records, metadata, locking configuration, and access control — without requiring any special permissions.
Prerequisites
- An existing Audit Trail on the IOTA network
In the examples below an admin-client owning an admin role capability is used to create the AuditTrail object as been
shown in Create an Audit Trail. It is not necessarily needed to access AuditTrail objects
for read only purposes.
Available Read-Only Methods
Every AuditTrail object supports a comprehensive read-only interface:
- Trail inspection: Name, description, creator, creation timestamp, updatable metadata
- Record access: Fetch individual records by sequence number, list all records, paginated listing, record count
- Locking queries: Check if a specific record is locked, inspect the locking configuration
- Access control: Inspect roles, permissions, and the revoked capabilities denylist
- Tag registry: View registered tags and their usage counts
1. Set Up Multiple Wallets
Create an admin wallet to create the trail and a record-admin wallet to add a record, so there is on-chain state to inspect.
Used Utility Functions
2. Set Up Read-Only Client
You can use either a full client or a read-only client for inspection:
3. Fetch Trail State
Load the full on-chain trail object to access metadata, locking configuration, and access control state:
4. List and Paginate Records
Access records with full pagination support:
Read-Only Methods Summary
| Method | Returns | Description |
|---|---|---|
get() | OnChainAuditTrail | Full trail state including metadata, roles, and locking config |
records().get(seq) | Record | Single record by sequence number |
records().list() | Record[] | All records (expensive for large trails) |
records().listWithLimit(n) | Record[] | Records with a cap on the number returned |
records().listPage(cursor, limit) | PaginatedRecord | Paginated record listing (max 1000 per page) |
records().recordCount() | u64 | Total number of records in the trail |
locking().isRecordLocked(seq) | bool | Whether a specific record is locked by the locking configuration |
Use Cases for Read-Only Methods
Auditing and Compliance
- Verify trail integrity: Inspect the complete record history with sequence numbers and timestamps
- Track corrections: Follow correction chains to understand how data has evolved
- Compliance checking: Verify that locking configuration meets regulatory requirements
Integration and Automation
- Status monitoring: Check trail state and record count for operational dashboards
- Content verification: Compare on-chain records against off-chain source data
- Lock awareness: Check whether records are locked before attempting deletion
User Interfaces
- Display records: Show record data, metadata, tags, and timestamps
- Pagination: Navigate large trails with cursor-based pagination
- Access control overview: Display roles, permissions, and capability status