Skip to main content

NotarizationClient

@iota/notarization API documentation

Class: NotarizationClient

Read-write client for creating and modifying notarizations on the IOTA ledger.

Remarks​

Wraps a NotarizationClientReadOnly together with a transaction signer. Use the builder methods (NotarizationClient.createDynamic, NotarizationClient.createLocked) to create new notarizations and the mutation methods (NotarizationClient.updateState, NotarizationClient.updateMetadata, NotarizationClient.destroy, NotarizationClient.transferNotarization) to operate on existing ones. For pure read access, prefer NotarizationClientReadOnly.

Methods​

create()​

static create(client, signer): Promise<NotarizationClient>

Constructs a read-write client by attaching a signer to a read-only client.

Parameters​

client​

NotarizationClientReadOnly

A NotarizationClientReadOnly connected to the target network.

signer​

TransactionSigner

A TransactionSigner responsible for signing outgoing transactions.

Returns​

Promise<NotarizationClient>

A connected NotarizationClient.

Throws​

When the signer's public key cannot be retrieved.

createDynamic()​

createDynamic(): NotarizationBuilderDynamic

Starts building a Dynamic-Notarization.

Returns​

NotarizationBuilderDynamic

A fresh NotarizationBuilderDynamic.

Emits a DynamicNotarizationCreated event on success.

Remarks​

On execution the resulting transaction transfers the new notarization object to the sender.

createLocked()​

createLocked(): NotarizationBuilderLocked

Starts building a Locked-Notarization.

Returns​

NotarizationBuilderLocked

A fresh NotarizationBuilderLocked.

Emits a LockedNotarizationCreated event on success.

Remarks​

On execution the resulting transaction transfers the new notarization object to the sender.

destroy()​

destroy(notarization_id): any

Builds a transaction that destroys a notarization permanently and releases its object ID.

Parameters​

notarization_id​

string

Returns​

any

A TransactionBuilder wrapping the DestroyNotarization transaction.

Remarks​

All package-local TimeLocks of the attached LockMetadata are destroyed in the process. The notarization must currently be destroy-allowed (see NotarizationClientReadOnly.isDestroyAllowed); otherwise the on-chain transaction aborts.

Throws​

When the ID is malformed.

Emits a NotarizationDestroyed event on success.

iotaClient()​

iotaClient(): IotaClient

The underlying IOTA client used for ledger queries.

Returns​

IotaClient

network()​

network(): string

The network identifier this client is connected to.

Returns​

string

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

readOnly()​

readOnly(): NotarizationClientReadOnly

Returns a read-only view of this client.

Returns​

NotarizationClientReadOnly

A NotarizationClientReadOnly sharing the same network connection.

senderAddress()​

senderAddress(): string

The IOTA address transactions will be sent from.

Returns​

string

senderPublicKey()​

senderPublicKey(): PublicKey

The signer's public key.

Returns​

PublicKey

Throws​

When the signer fails to provide its public key.

signer()​

signer(): TransactionSigner

The transaction signer attached to this client.

Returns​

TransactionSigner

tfComponentsPackageId()​

tfComponentsPackageId(): string

Returns the tf_components package ID currently in use.

Returns​

string

Stringified object ID of the resolved tf_components package.

transferNotarization()​

transferNotarization(notarization_id, recipient): any

Builds a transaction that transfers ownership of a notarization to another address.

Parameters​

notarization_id​

string

recipient​

string

The new owner's IOTA address.

Returns​

any

A TransactionBuilder wrapping the TransferNotarization transaction.

Remarks​

Permitted only when the notarization has no LockMetadata or when its transferLock is not currently active.

Behaviour depends on the Notarization Method:

  • Dynamic: on success the notarization is transferred to recipient. Submitting while the configured transferLock is currently engaged aborts on-chain.
  • Locked: always aborts on-chain — Locked-Notarizations have their transferLock pinned to TimeLockType.UntilDestroyed and are therefore non-transferable.

Throws​

When the ID or address is malformed.

Emits a DynamicNotarizationTransferred event on success.

updateMetadata()​

updateMetadata(metadata, notarization_id): any

Builds a transaction that replaces the updatable metadata of a notarization.

Parameters​

metadata​

The replacement metadata, or null to clear it.

undefined | null | string

notarization_id​

string

Returns​

any

A TransactionBuilder wrapping the UpdateMetadata transaction.

Remarks​

Does not affect the state, stateVersionCount, lastStateChangeAt, or the immutable description.

Behaviour depends on the Notarization Method:

  • Dynamic: always permitted — the underlying updateLock is fixed to TimeLockType.None.
  • Locked: always aborts on-chain, because the underlying updateLock is pinned to TimeLockType.UntilDestroyed.

Throws​

When the ID is malformed.

updateState()​

updateState(new_state, notarization_id): any

Builds a transaction that replaces the state of a notarization.

Parameters​

new_state​

State

notarization_id​

string

Returns​

any

A TransactionBuilder wrapping the UpdateState transaction.

Remarks​

On success the on-chain transaction replaces state with newState, increments stateVersionCount by 1, and refreshes lastStateChangeAt to the on-chain clock (in milliseconds since the Unix epoch).

Behaviour depends on the Notarization Method:

  • Dynamic: always permitted — the underlying updateLock is fixed to TimeLockType.None.
  • Locked: always aborts on-chain, because the underlying updateLock is pinned to TimeLockType.UntilDestroyed.

Throws​

When the ID is malformed.

Emits a NotarizationUpdated event on success.