Skip to main content

NotarizationClientReadOnly

@iota/notarization API documentation

Class: NotarizationClientReadOnly

Read-only client for inspecting notarization objects on the IOTA ledger.

Remarks​

This client never signs or submits transactions; use NotarizationClient for write operations. All accessor methods take a notarization object ID and return the corresponding on-chain value.

Methods​

chainId()​

chainId(): string

The chain ID this client is connected to.

Returns​

string

create()​

static create(iota_client): Promise<NotarizationClientReadOnly>

Constructs a read-only client and resolves the notarization package for the network the given IOTA client is connected to.

Parameters​

iota_client​

IotaClient

Returns​

Promise<NotarizationClientReadOnly>

A connected NotarizationClientReadOnly.

Throws​

When the network cannot be queried or no notarization package is available for it.

createWithPkgId()​

static createWithPkgId(iota_client, iota_notarization_pkg_id): Promise<NotarizationClientReadOnly>

Constructs a read-only client pinned to a specific notarization package ID.

Parameters​

iota_client​

IotaClient

iota_notarization_pkg_id​

string

Returns​

Promise<NotarizationClientReadOnly>

A connected NotarizationClientReadOnly.

Remarks​

Use this when you need to interact with a particular package version, e.g. for replaying historical state, instead of letting the client resolve the latest package on the network.

Throws​

When the package ID cannot be parsed or the network cannot be queried.

createdAtTs()​

createdAtTs(notarized_object_id): Promise<bigint>

Fetches the creation timestamp.

Parameters​

notarized_object_id​

string

Returns​

Promise<bigint>

Milliseconds since the Unix epoch.

Throws​

When the ID is malformed or the object cannot be fetched.

description()​

description(notarized_object_id): Promise<undefined | string>

Fetches the immutable description set at creation, if any.

Parameters​

notarized_object_id​

string

Returns​

Promise<undefined | string>

The description string, or null when none was set.

Throws​

When the ID is malformed or the object cannot be fetched.

getNotarizationById()​

getNotarizationById(notarized_object_id): Promise<OnChainNotarization>

Fetches the on-chain representation of a notarization.

Parameters​

notarized_object_id​

string

Returns​

Promise<OnChainNotarization>

The OnChainNotarization for the given ID.

Throws​

When the ID is malformed or no notarization with that ID exists on the connected network.

iotaClient()​

iotaClient(): IotaClient

The underlying IOTA client used for ledger queries.

Returns​

IotaClient

isDestroyAllowed()​

isDestroyAllowed(notarized_object_id): Promise<boolean>

Checks whether the notarization can currently be destroyed.

Parameters​

notarized_object_id​

string

Returns​

Promise<boolean>

true if NotarizationClient.destroy would currently succeed, false otherwise.

Remarks​

Behaviour depends on the Notarization Method:

  • Dynamic: destruction is gated only on the transferLock. The notarization is destroy-allowed unless transferLock is currently UnlockAt-locked.
  • Locked: destruction is gated on updateLock, deleteLock, and transferLock. The notarization is destroy-allowed only when none of them is currently UnlockAt-locked.

Throws​

When the ID is malformed or the object cannot be fetched.

isTransferLocked()​

isTransferLocked(notarized_object_id): Promise<boolean>

Checks whether ownership transfers are currently locked.

Parameters​

notarized_object_id​

string

Returns​

Promise<boolean>

true if NotarizationClient.transferNotarization would currently abort, false otherwise.

Remarks​

Result depends on the Notarization Method:

  • Dynamic: true when the configured transferLock is engaged.
  • Locked: always true — Locked-Notarizations are non-transferable by design.

Throws​

When the ID is malformed or the object cannot be fetched.

isUpdateLocked()​

isUpdateLocked(notarized_object_id): Promise<boolean>

Checks whether state updates are currently locked.

Parameters​

notarized_object_id​

string

Returns​

Promise<boolean>

true if state updates are currently rejected, false otherwise.

Remarks​

Result depends on the Notarization Method:

  • Dynamic: always false.
  • Locked: true while the configured updateLock is engaged.

Throws​

When the ID is malformed or the object cannot be fetched.

lastStateChangeTs()​

lastStateChangeTs(notarized_object_id): Promise<bigint>

Fetches the timestamp of the most recent state change.

Parameters​

notarized_object_id​

string

Returns​

Promise<bigint>

Milliseconds since the Unix epoch.

Throws​

When the ID is malformed or the object cannot be fetched.

lockMetadata()​

lockMetadata(notarized_object_id): Promise<undefined | LockMetadata>

Fetches the LockMetadata attached at creation, if any.

Parameters​

notarized_object_id​

string

Returns​

Promise<undefined | LockMetadata>

The LockMetadata, or null when none is attached.

Throws​

When the ID is malformed or the object cannot be fetched.

network()​

network(): string

The network identifier (e.g. "mainnet", "testnet") this client is connected to.

Returns​

string

notarizationMethod()​

notarizationMethod(notarized_object_id): Promise<NotarizationMethod>

Fetches the NotarizationMethod of a notarization.

Parameters​

notarized_object_id​

string

Returns​

Promise<NotarizationMethod>

The notarization's NotarizationMethod.

Throws​

When the ID is malformed or the object cannot be fetched.

packageHistory()​

packageHistory(): string[]

The full history of notarization package IDs known on this network, most recent first.

Returns​

string[]

packageId()​

packageId(): string

The notarization package ID this client is using.

Returns​

string

state()​

state(notarized_object_id): Promise<State>

Fetches the current State of a notarization.

Parameters​

notarized_object_id​

string

Returns​

Promise<State>

The current State.

Throws​

When the ID is malformed or the object cannot be fetched.

stateVersionCount()​

stateVersionCount(notarized_object_id): Promise<bigint>

Fetches the number of state versions a notarization has gone through.

Parameters​

notarized_object_id​

string

Returns​

Promise<bigint>

The count, where 0 means the state has not been updated since creation.

Throws​

When the ID is malformed or the object cannot be fetched.

tfComponentsPackageId()​

tfComponentsPackageId(): string

Returns the tf_components package ID currently in use.

Returns​

string

Stringified object ID of the resolved tf_components package.

updatableMetadata()​

updatableMetadata(notarized_object_id): Promise<undefined | string>

Fetches the current updatable metadata, if any.

Parameters​

notarized_object_id​

string

Returns​

Promise<undefined | string>

The metadata string, or null when none is set.

Throws​

When the ID is malformed or the object cannot be fetched.