TrailRecords
@iota/audit-trails API documentation
Class: TrailRecords
Record API scoped to a specific trail.
Remarks
Builds record-oriented transactions and loads record data from the trail's linked-table storage.
Methods
toJSON()
toJSON():
Object
- Return copy of self without private attributes.
Returns
Object
toString()
toString():
string
Return stringified version of self.
Returns
string
add()
add(
data,metadata?,tag?):TransactionBuilder<AddRecord>
Builds a record-add transaction.
Parameters
data
Data payload of the new record.
metadata?
Optional application-defined metadata stored alongside the record.
string | null
tag?
Optional trail-owned tag attached to the record.
string | null
Returns
A TransactionBuilder wrapping the AddRecord transaction.
Remarks
Records are appended sequentially with auto-assigned, monotonically increasing sequence
numbers that are never reused. While the trail's writeLock is active the on-chain call
aborts. When tag is set, it must already exist in the trail's record-tag registry and the
supplied capability's role must allow that tag.
Requires the Permission.AddRecord permission.
Throws
When the wrapper was created from a read-only client.
Emits a RecordAdded event on success.
correct()
correct(
replaces,data,metadata?):Promise<Empty>
Executes the correction helper for a record payload.
Parameters
replaces
BigUint64Array
Sequence numbers of the records that the correction supersedes.
data
Replacement record payload.
metadata?
Optional application-defined metadata stored alongside the correction.
string | null
Returns
Promise<Empty>
Remarks
Placeholder for a future correction helper — currently always throws because the underlying implementation is not yet wired up.
Throws
Always; the helper is not yet implemented.
delete()
delete(
sequence_number):TransactionBuilder<DeleteRecord>
Builds a single-record delete transaction.
Parameters
sequence_number
bigint
Returns
TransactionBuilder<DeleteRecord>
A TransactionBuilder wrapping the DeleteRecord transaction.
Remarks
The on-chain call aborts when no record exists at sequenceNumber or while the configured
delete-record window still protects it. When the record carries a tag, the supplied
capability's role must allow that tag.
Requires the Permission.DeleteRecord permission.
Throws
When the wrapper was created from a read-only client.
Emits a RecordDeleted event on success.
deleteBatch()
deleteBatch(
limit):TransactionBuilder<DeleteRecordsBatch>
Builds a batched record-delete transaction.
Parameters
limit
bigint
Maximum number of records to delete in this batch.
Returns
TransactionBuilder<DeleteRecordsBatch>
A TransactionBuilder wrapping the DeleteRecordsBatch transaction;
when applied it resolves to the sequence numbers of the records deleted in this batch, in
deletion order — at most limit entries, possibly fewer.
Remarks
Walks the trail from the front and silently skips records still inside the delete-record
window or whose tag the capability does not allow, deleting up to limit eligible records
in trail order. The set of locked records is fixed at the start of the on-chain call:
count-based windows protect the last count records present when the call begins, and
time-based windows are evaluated against the clock timestamp captured at that point.
Running this batch with limit therefore yields the same final trail state as deleting
each eligible sequence number one at a time, provided the locking configuration is not
mutated and no records are appended between calls.
limit caps the number of records actually deleted, not the number of records inspected.
Ineligible records at the front of the trail are silently walked past without counting
toward limit, so more than limit records may be visited before limit deletions
accumulate.
Requires the Permission.DeleteAllRecords permission.
Throws
When the wrapper was created from a read-only client.
Emits one RecordDeleted event per deletion.
get()
get(
sequence_number):Promise<Record>
Loads one record by sequence number.
Parameters
sequence_number
bigint
Returns
Promise<Record>
The record stored at sequenceNumber.
Throws
When no record exists at the requested sequence number or the data cannot be deserialized.
list()
list():
Promise<Record[]>
Lists all records in sequence-number order.
Returns
Promise<Record[]>
Every record in the trail, sorted by ascending sequence number.
Remarks
Traverses the full on-chain linked table and can be expensive for large trails. For paginated access, use TrailRecords.listPage.
Throws
When the trail object cannot be fetched or a record cannot be deserialized.
listPage()
listPage(
cursor,limit):Promise<PaginatedRecord>
Loads one page of records starting at cursor.
Parameters
cursor
Sequence-number cursor for the page boundary; pass null for the first
page and reuse PaginatedRecord.nextCursor for subsequent pages.
bigint | null | undefined
limit
number
Maximum number of records to return; may not exceed the maximum page size defined in the Audit Trails Rust crate.
Returns
Promise<PaginatedRecord>
A PaginatedRecord carrying the loaded records and pagination metadata.
Throws
When the trail object cannot be fetched, a record cannot be deserialized, or
limit exceeds the maximum page size defined in the Audit Trails Rust crate.
listWithLimit()
listWithLimit(
max_entries):Promise<Record[]>
Lists all records while enforcing a maximum number of entries.
Parameters
max_entries
number
Returns
Promise<Record[]>
Every record in the trail, sorted by ascending sequence number.
Remarks
Use this as a safety net against unexpectedly large traversals.
Throws
When the trail's linked-table size exceeds maxEntries.
recordCount()
recordCount():
Promise<bigint>
Returns the number of records currently stored in the trail.
Returns
Promise<bigint>
Current record count.
Throws
When the trail object cannot be fetched.