Skip to main content

AuditTrailHandle

@iota/audit-trails API documentation

Class: AuditTrailHandle

Handle bound to a specific audit-trail object.

Remarks​

AuditTrailHandle keeps one trail ID together with the originating client so all trail-scoped reads and transaction builders can be discovered from a single value. Use the subsystem accessors AuditTrailHandle.records, AuditTrailHandle.access, AuditTrailHandle.locking, and AuditTrailHandle.tags to reach the corresponding APIs.

Methods​

toJSON()​

toJSON(): Object

  • Return copy of self without private attributes.

Returns​

Object

toString()​

toString(): string

Return stringified version of self.

Returns​

string

access()​

access(): TrailAccess

Returns the access-control API scoped to this trail.

Returns​

TrailAccess

A TrailAccess wrapper bound to this trail.

Remarks​

Use this for roles, capabilities, and access-policy updates.

deleteAuditTrail()​

deleteAuditTrail(): TransactionBuilder<DeleteAuditTrail>

Builds a delete transaction for this trail.

Returns​

TransactionBuilder<DeleteAuditTrail>

A TransactionBuilder wrapping the DeleteAuditTrail transaction.

Remarks​

Deletion additionally requires the trail to be empty (the on-chain call aborts otherwise) and the configured deleteTrailLock to have elapsed.

Requires the Permission.DeleteAuditTrail permission.

Throws​

When the handle was created from a read-only client.

Emits an AuditTrailDeleted event on success.

get()​

get(): Promise<OnChainAuditTrail>

Loads the full on-chain trail object.

Returns​

Promise<OnChainAuditTrail>

The current OnChainAuditTrail state of this trail.

Remarks​

Each call fetches a fresh snapshot from chain state.

Throws​

When the trail object cannot be fetched or decoded.

locking()​

locking(): TrailLocking

Returns the locking API scoped to this trail.

Returns​

TrailLocking

A TrailLocking wrapper bound to this trail.

Remarks​

Use this for inspecting lock state and updating locking rules.

migrate()​

migrate(): TransactionBuilder<Migrate>

Builds a migration transaction for this trail.

Returns​

TransactionBuilder<Migrate>

A TransactionBuilder wrapping the Migrate transaction.

Remarks​

Bumps the trail's stored data layout to the current package version. Intended to be called once after the Audit Trails Move Package is upgraded.

Requires the Permission.Migrate permission.

Throws​

When the handle was created from a read-only client.

Emits an AuditTrailMigrated event on success.

records()​

records(): TrailRecords

Returns the record API scoped to this trail.

Returns​

TrailRecords

A TrailRecords wrapper bound to this trail.

Remarks​

Use this for record reads, appends, and deletions.

tags()​

tags(): TrailTags

Returns the tag-registry API scoped to this trail.

Returns​

TrailTags

A TrailTags wrapper bound to this trail.

Remarks​

Use this for managing the canonical tag registry that record writes and role-tag restrictions must reference.

updateMetadata()​

updateMetadata(metadata?): TransactionBuilder<UpdateMetadata>

Builds a mutable-metadata update transaction for this trail.

Parameters​

metadata?​

New value for the trail's updatableMetadata field, or null to clear it.

string | null

Returns​

TransactionBuilder<UpdateMetadata>

A TransactionBuilder wrapping the UpdateMetadata transaction.

Remarks​

Replaces or clears the trail's updatableMetadata field.

Requires the Permission.UpdateMetadata permission.

Throws​

When the handle was created from a read-only client.

Emits a MetadataUpdated event on success.