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(
sequence_number,data,metadata?,tag?):TransactionBuilder<CorrectRecord>
Builds a record-correction transaction.
Parameters
sequence_number
bigint
data
Replacement record payload.
metadata?
Optional application-defined metadata stored alongside the correction.
string | null
tag?
Optional trail-owned tag attached to the correction.
string | null
Returns
TransactionBuilder<CorrectRecord>
A TransactionBuilder wrapping the CorrectRecord transaction.
Remarks
Appends a new correction record that supersedes sequenceNumber while preserving the
original record. The correction records the sequence number it replaces, and the replaced
record receives a back-pointer to the new correction so resolveCurrent can follow the
replacement chain.
Tagged corrections require the correction tag to exist in the trail registry and the supplied capability's role to allow both the replaced record's tag, when present, and the correction record's tag, when present. The transaction aborts on-chain when the package version is incompatible, the capability is invalid, the trail is write-locked, the target record does not exist, the target record was already replaced, or tag authorization fails.
Requires the Permission.CorrectRecord permission.
Throws
When the wrapper was created from a read-only client.
Emits a RecordAdded event on success.
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.
resolveCurrent()
resolveCurrent(
sequence_number):Promise<Record>
Loads the current version of a record by following correction links.
Parameters
sequence_number
bigint
Returns
Promise<Record>
The current record at the end of the correction chain.
Remarks
Use TrailRecords.get when you need the exact immutable record stored at a sequence
number. Use resolveCurrent when you have an original sequence number and want the latest
correction in that record's replacement chain.
For example, if record 3 was corrected by record 7, and record 7 was later corrected
by record 9, resolveCurrent(3) returns record 9. If the starting record has not been
replaced, this returns the starting record itself.
Throws
When a record cannot be loaded or the replacement chain is malformed.