Skip to main content

AuditTrailBuilder

@iota/audit-trails API documentation

Class: AuditTrailBuilder

Builder that assembles the parameters for creating a new audit trail.

Remarks​

The resulting transaction publishes the trail as a shared object, seeds the reserved Admin role with the permission set returned by PermissionSet.adminPermissions, and transfers a freshly minted initial-admin Capability to the configured admin address. An admin address must be set (either through AuditTrailBuilder.withAdmin or by constructing the builder via AuditTrailClient.createTrail, which seeds it with the signer); otherwise AuditTrailBuilder.finish produces a transaction that fails to build. When an initial record is set, its tag — if any — must already be in the configured record-tag list.

Methods​

toJSON()​

toJSON(): Object

  • Return copy of self without private attributes.

Returns​

Object

toString()​

toString(): string

Return stringified version of self.

Returns​

string

finish()​

finish(): TransactionBuilder<CreateTrail>

Finalizes the builder into a transaction wrapper.

Returns​

TransactionBuilder<CreateTrail>

A TransactionBuilder wrapping the CreateTrail transaction.

Remarks​

On execution the audit-trail package shares the new trail object, seeds the reserved Admin role with the permission set returned by PermissionSet.adminPermissions, transfers an initial-admin capability to the configured admin address, and optionally stores the initial record at sequence number 0.

Throws​

When the builder is missing a required field or its initial record references a tag that is not in the record-tag list, or when the configured LockingConfig is invalid (for example, a count-based delete window with count == 0).

Emits an AuditTrailCreated event on success.

withAdmin()​

withAdmin(admin): AuditTrailBuilder

Sets the initial admin address.

Parameters​

admin​

string

Address that will receive the initial-admin capability.

Returns​

AuditTrailBuilder

The same builder, with the admin address configured.

Remarks​

On execution the trail's role map is seeded with a single role named "Admin" carrying the permission set returned by PermissionSet.adminPermissions, and a freshly minted initial-admin capability is transferred to this address. Setting an admin is required before AuditTrailBuilder.finish can produce a viable transaction; constructing the builder via AuditTrailClient.createTrail already seeds it with the signer address.

Throws​

When admin is not a valid IOTA address.

withInitialRecordBytes()​

withInitialRecordBytes(data, metadata?, tag?): AuditTrailBuilder

Sets the initial record using a raw byte payload.

Parameters​

data​

Uint8Array

Raw bytes stored as the initial record payload.

metadata?​

Optional application-defined metadata stored alongside the record.

string | null

tag?​

Optional trail-owned tag attached to the record.

string | null

Returns​

AuditTrailBuilder

The same builder, with the initial record configured.

Remarks​

The record is stored at sequence number 0. When tag is provided it must already appear in the list passed to AuditTrailBuilder.withRecordTags; the on-chain call aborts otherwise. Bumps the tag's usage count on success.

withInitialRecordString()​

withInitialRecordString(data, metadata?, tag?): AuditTrailBuilder

Sets the initial record using a UTF-8 string payload.

Parameters​

data​

string

UTF-8 text payload for the initial record.

metadata?​

Optional application-defined metadata stored alongside the record.

string | null

tag?​

Optional trail-owned tag attached to the record.

string | null

Returns​

AuditTrailBuilder

The same builder, with the initial record configured.

Remarks​

The record is stored at sequence number 0.

When tag is provided it must already appear in the list passed to AuditTrailBuilder.withRecordTags; the on-chain call aborts otherwise. Bumps the tag's usage count on success.

withLockingConfig()​

withLockingConfig(config): AuditTrailBuilder

Sets the LockingConfig for the trail.

Parameters​

config​

LockingConfig

Combined delete-record window, delete-trail lock, and write lock.

Returns​

AuditTrailBuilder

The same builder, with the locking configuration applied.

Remarks​

config.deleteTrailLock must not be TimeLock.withUntilDestroyed; trail creation aborts on-chain otherwise.

withRecordTags()​

withRecordTags(tags): AuditTrailBuilder

Sets the canonical list of record tags owned by the trail.

Parameters​

tags​

string[]

Tag names that the trail will recognize.

Returns​

AuditTrailBuilder

The same builder, with the record-tag registry configured.

Remarks​

Every tag name later referenced by an initial record, an TrailRecords.add call, or a role's RoleTags allowlist must appear in this list. Tags are inserted with a usage count of zero.

withTrailMetadata()​

withTrailMetadata(name, description?): AuditTrailBuilder

Sets the trail's ImmutableMetadata (name and optional description).

Parameters​

name​

string

Human-readable trail name.

description?​

Optional human-readable description.

string | null

Returns​

AuditTrailBuilder

The same builder, with the immutable metadata configured.

Remarks​

Stored once at trail creation and exposed read-only thereafter. Use AuditTrailBuilder.withUpdatableMetadata for the mutable counterpart.

withUpdatableMetadata()​

withUpdatableMetadata(metadata): AuditTrailBuilder

Sets the trail's updatableMetadata field.

Parameters​

metadata​

string

Initial value of the trail's updatableMetadata field.

Returns​

AuditTrailBuilder

The same builder, with the updatable metadata configured.

Remarks​

This field can later be replaced or cleared by holders of Permission.UpdateMetadata via AuditTrailHandle.updateMetadata.