Refactor Transaction interface (#1621)

* TxBuilder

* partial gas data in TxBuilder

* Lazily compute programmable transaction

* Merge IntoProgrammableTransaction into TxEffect

* sponsor tx in build

* allow sponsoring with partial gas information

* publishing DID document uses new transaction API

* update authenticated asset code to use the new transaction API

* make IotaTransactionBlockEffects available for WASM

* all operations use the new transaction API

* ensure tests work

* WASM buildable

* avoid the use of bcs when possible

* fix tests, fmt and clippy

* create_did and update_did

* fix ts typing

* even better ts

* re-add ts examples and tests

* fix deactivate_did

* config change TS

* WASM send proposal

* clippy

* fix partial gas data bug

* advanced transaction example

* TS advanced transaction example

* fix merge bug

* fmt, clippy, fixes

* fix feature flag issue

* Apply suggestions from code review

Co-authored-by: wulfraem <[email protected]>

* review comments

* Apply suggestions from code review

Co-authored-by: wulfraem <[email protected]>

* review comments

* use published version of iota-interaction-ts

* use iota-interaction-ts ^0.3.0

* fmt

* make tokio an unconditional dependency

* tokio issue

* Update identity_iota_core/src/rebased/proposals/borrow.rs

Co-authored-by: wulfraem <[email protected]>

* Tx application error

* adapt rust code to use new Transaction::apply

* Fix new apply implementations

* adapt wasm code to use the new apply function

* fix example

* fmt, grammar

* missing license header

* Merge branch 'main' into feat/transaction-interface-refactor

* Merge branch 'main' into feat/transaction-interface-refactor

* clippy & fmt

* fmt clippy

* adapt keytool example to use new transaction API

* Fix keytool integration

---------

Co-authored-by: wulfraem <[email protected]>

Author: UMR1352

bindings/wasm/identity_wasm/Cargo.toml

@@ -18,6 +18,7 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 anyhow = "1.0.95"
 async-trait = { version = "0.1", default-features = false }
+bcs = "0.1.6"
 console_error_panic_hook = { version = "0.1" }
 fastcrypto = { git = "https://github.com/MystenLabs/fastcrypto", rev = "2f502fd8570fe4e9cff36eea5bbd6fef22002898", package = "fastcrypto" }
 identity_ecdsa_verifier = { path = "../../../identity_ecdsa_verifier", default-features = false, features = ["es256", "es256k"] }

bindings/wasm/identity_wasm/examples/src/0_basic/0_create_did.ts

@@ -24,7 +24,7 @@ export async function createIdentity(): Promise<void> {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     did = identity.didDocument().id();
 
     // check if we can resolve it via client

bindings/wasm/identity_wasm/examples/src/0_basic/1_update_did.ts

@@ -25,7 +25,7 @@ export async function updateIdentity() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const did = identity.didDocument().id();
 
     // Resolve the latest state of the document.
@@ -56,10 +56,12 @@ export async function updateIdentity() {
     let originalMethod = resolved.resolveMethod(vmFragment1) as VerificationMethod;
     await resolved.purgeMethod(storage, originalMethod?.id());
 
+    let controllerToken = await identity.getControllerToken(identityClient);
+
     let maybePendingProposal = await identity
-        .updateDidDocument(resolved.clone())
+        .updateDidDocument(resolved.clone(), controllerToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(identityClient)
+        .buildAndExecute(identityClient)
         .then(result => result.output);
 
     console.assert(maybePendingProposal == null, "the proposal should have been executed right away!");

bindings/wasm/identity_wasm/examples/src/0_basic/2_resolve_did.ts

@@ -28,7 +28,7 @@ export async function resolveIdentity() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const did = identity.didDocument().id();
 
     // Resolve the associated identity and extract the DID document from it.

bindings/wasm/identity_wasm/examples/src/0_basic/3_deactivate_did.ts

@@ -17,19 +17,20 @@ export async function deactivateIdentity() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const did = identity.didDocument().id();
 
     // Resolve the latest state of the document.
     // Technically this is equivalent to the document above.
     const resolved = await identityClient.resolveDid(did);
     console.log("Resolved DID document:", JSON.stringify(resolved, null, 2));
 
+    const controllerToken = await identity.getControllerToken(identityClient);
     // Deactivate the DID.
     await identity
-        .deactivateDid()
+        .deactivateDid(controllerToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
 
     // Resolving a deactivated DID returns an empty DID document
     // with its `deactivated` metadata field set to `true`.
@@ -42,9 +43,9 @@ export async function deactivateIdentity() {
     // Re-activate the DID by publishing a valid DID document.
     console.log("Publishing this:", JSON.stringify(resolved, null, 2));
     await identity
-        .updateDidDocument(resolved)
+        .updateDidDocument(resolved, controllerToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
 
     // Resolve the reactivated DID document.
     let resolvedReactivated = await identityClient.resolveDid(did);

bindings/wasm/identity_wasm/examples/src/0_basic/4_delete_did.ts

@@ -17,19 +17,21 @@ export async function deleteIdentityDID() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const did = identity.didDocument().id();
 
     // Resolve the latest state of the document.
     // Technically this is equivalent to the document above.
     const resolved = await identityClient.resolveDid(did);
     console.log("Resolved DID document:", JSON.stringify(resolved, null, 2));
 
+    const controllerToken = await identity.getControllerToken(identityClient);
+
     // delete the DID.
     await identity
-        .deleteDid()
+        .deleteDid(controllerToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
 
     // After an Identity's DID has been deleted, the document will be
     // empty and inactive. Identity.hasDeletedDid must return `true`.
@@ -49,9 +51,9 @@ export async function deleteIdentityDID() {
     // Trying to update a deleted DID must fail!
     try {
         await identity
-            .updateDidDocument(resolved)
+            .updateDidDocument(resolved, controllerToken!)
             .withGasBudget(TEST_GAS_BUDGET)
-            .execute(identityClient);
+            .buildAndExecute(identityClient);
     } catch (_) {
         console.log("A deleted DID cannot be updated!");
     }

bindings/wasm/identity_wasm/examples/src/0_basic/5_create_vc.ts

@@ -30,7 +30,7 @@ export async function createVC() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     const issuerDocument = issuerIdentity.didDocument();
 
     // Create an identity for the holder, and publish DID document for it, in this case also the subject.
@@ -40,7 +40,7 @@ export async function createVC() {
     const { output: aliceIdentity } = await aliceClient
         .createIdentity(unpublishedAliceDocument)
         .finish()
-        .execute(aliceClient);
+        .buildAndExecute(aliceClient);
     const aliceDocument = aliceIdentity.didDocument();
 
     // Create a credential subject indicating the degree earned by Alice, linked to their DID.

bindings/wasm/identity_wasm/examples/src/0_basic/6_create_vp.ts

@@ -46,7 +46,7 @@ export async function createVP() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     const issuerDocument = issuerIdentity.didDocument();
 
     // create holder account, create identity, and publish DID document for it
@@ -56,7 +56,7 @@ export async function createVP() {
     const { output: aliceIdentity } = await aliceClient
         .createIdentity(unpublishedAliceDocument)
         .finish()
-        .execute(aliceClient);
+        .buildAndExecute(aliceClient);
     const aliceDocument = aliceIdentity.didDocument();
 
     // ===========================================================================

bindings/wasm/identity_wasm/examples/src/0_basic/7_revoke_vc.ts

@@ -52,7 +52,7 @@ export async function revokeVC() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     let issuerDocument = issuerIdentity.didDocument();
 
     // create holder account, create identity, and publish DID document for it.
@@ -62,7 +62,7 @@ export async function revokeVC() {
     const { output: aliceIdentity } = await aliceClient
         .createIdentity(unpublishedAliceDocument)
         .finish()
-        .execute(aliceClient);
+        .buildAndExecute(aliceClient);
     const aliceDocument = aliceIdentity.didDocument();
 
     // Create a new empty revocation bitmap. No credential is revoked yet.
@@ -73,11 +73,13 @@ export async function revokeVC() {
     const service: Service = revocationBitmap.toService(serviceId);
     issuerDocument.insertService(service);
 
+    const issuerIdentityToken = await issuerIdentity.getControllerToken(issuerClient);
+
     // Publish the updated document.
     await issuerIdentity
-        .updateDidDocument(issuerDocument)
+        .updateDidDocument(issuerDocument, issuerIdentityToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
 
     // Create a credential subject indicating the degree earned by Alice, linked to their DID.
     const subject = {
@@ -131,9 +133,9 @@ export async function revokeVC() {
 
     // Publish the changes.
     await issuerIdentity
-        .updateDidDocument(issuerDocument)
+        .updateDidDocument(issuerDocument, issuerIdentityToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
 
     // Credential verification now fails.
     try {
@@ -161,9 +163,9 @@ export async function revokeVC() {
 
     // Publish the changes.
     await issuerIdentity
-        .updateDidDocument(issuerDocument)
+        .updateDidDocument(issuerDocument, issuerIdentityToken!)
         .withGasBudget(TEST_GAS_BUDGET)
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
 
     issuerDocument = issuerIdentity.didDocument();
 

bindings/wasm/identity_wasm/examples/src/1_advanced/11_advanced_transactions.ts

@@ -0,0 +1,52 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { IdentityClient, IotaDocument } from "@iota/identity-wasm/node";
+import { IotaClient } from "@iota/iota-sdk/client";
+import { TransactionDataBuilder } from "@iota/iota-sdk/transactions";
+import { getFundedClient, getMemstorage, NETWORK_URL } from "../util";
+
+/**
+ * This example demonstrates:
+ * 1. A user - Alice - can build a transaction that is sponsored by another user - Bob;
+ * 2. Deconstruct the transaction into its parts, to execute it manually through the SDK's IotaClient;
+ * 3. Apply the transaction's off-chain effects, from its on-chain ones.
+ */
+export async function advancedTransaction(): Promise<void> {
+    const aliceStorage = getMemstorage();
+    const aliceClient = await getFundedClient(aliceStorage);
+
+    const bobStorage = getMemstorage();
+    const bobClient = await getFundedClient(bobStorage);
+
+    const [txDataBcs, signatures, tx] = await aliceClient
+        .createIdentity(new IotaDocument(aliceClient.network()))
+        .finish()
+        .withSender(aliceClient.senderAddress())
+        .withSponsor(aliceClient.readOnly(), (tx_data: TransactionDataBuilder) => bobSponsorFn(tx_data, bobClient))
+        .then(txBuilder => txBuilder.build(aliceClient));
+
+    // create new client to connect to IOTA network
+    const iotaClient = new IotaClient({ url: NETWORK_URL });
+    const tx_response = await iotaClient.executeTransactionBlock({
+        transactionBlock: txDataBcs,
+        signature: signatures,
+        options: { showEffects: true },
+    });
+    await iotaClient.waitForTransaction({ digest: tx_response.digest });
+
+    const identity = await tx.apply(tx_response.effects!, aliceClient.readOnly());
+
+    console.log(`Alice successfully created Identity ${identity.id()}! Thanks for the gas Bob!`);
+}
+
+async function bobSponsorFn(tx_data: TransactionDataBuilder, client: IdentityClient): Promise<string> {
+    const coin = await client.iotaClient().getCoins({ owner: client.senderAddress(), coinType: "0x2::iota::IOTA" })
+        .then(res => res.data[0]);
+    tx_data.gasData.owner = client.senderAddress();
+    tx_data.gasData.price = 1000;
+    tx_data.gasData.budget = 50000000;
+    tx_data.gasData.payment = [{ version: coin.version, objectId: coin.coinObjectId, digest: coin.digest }];
+
+    return await client.signer().sign(tx_data.build());
+}

bindings/wasm/identity_wasm/examples/src/1_advanced/12_iota_keytool_integration.ts

@@ -52,8 +52,8 @@ export async function iotaKeytoolIntegration() {
 
     // Let's publish our new DID Document.
     let publishedDidDocument = await identityClient
-        .publishDidDocument(didDocument)
-        .execute(identityClient)
+        .publishDidDocument(didDocument, identityClient.senderAddress())
+        .buildAndExecute(identityClient)
         .then(res => res.output);
 
     console.log(`Here is our published DID document: ${JSON.stringify(publishedDidDocument, null, 2)}`);

bindings/wasm/identity_wasm/examples/src/1_advanced/4_custom_resolution.ts

@@ -66,7 +66,7 @@ export async function customResolution() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const did = identity.didDocument().id();
 
     // Construct a Resolver capable of resolving the did:key and iota methods.

bindings/wasm/identity_wasm/examples/src/1_advanced/5_domain_linkage.ts

@@ -34,7 +34,7 @@ export async function domainLinkage() {
     const { output: identity } = await identityClient
         .createIdentity(unpublished)
         .finish()
-        .execute(identityClient);
+        .buildAndExecute(identityClient);
     const document = identity.didDocument();
     const did = document.id();
 
@@ -53,7 +53,8 @@ export async function domainLinkage() {
         domains: [domainFoo, domainBar],
     });
     document.insertService(linkedDomainService.toService());
-    await identity.updateDidDocument(document).execute(identityClient);
+    const controllerToken = await identity.getControllerToken(identityClient);
+    await identity.updateDidDocument(document, controllerToken!).buildAndExecute(identityClient);
 
     let updatedDidDocument = identity.didDocument();
     console.log("Updated DID document:", JSON.stringify(updatedDidDocument, null, 2));

bindings/wasm/identity_wasm/examples/src/1_advanced/6_sd_jwt.ts

@@ -39,7 +39,7 @@ export async function sdJwt() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     const issuerDocument = issuerIdentity.didDocument();
 
     // Create an identity for the holder, and publish DID document for it, in this case also the subject.
@@ -49,7 +49,7 @@ export async function sdJwt() {
     const { output: aliceIdentity } = await aliceClient
         .createIdentity(unpublishedAliceDocument)
         .finish()
-        .execute(aliceClient);
+        .buildAndExecute(aliceClient);
     const aliceDocument = aliceIdentity.didDocument();
 
     // ===========================================================================

bindings/wasm/identity_wasm/examples/src/1_advanced/7_status_list_2021.ts

@@ -34,7 +34,7 @@ export async function statusList2021() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     const issuerDocument = issuerIdentity.didDocument();
 
     // Create an identity for the holder, and publish DID document for it, in this case also the subject.
@@ -44,7 +44,7 @@ export async function statusList2021() {
     const { output: aliceIdentity } = await aliceClient
         .createIdentity(unpublishedAliceDocument)
         .finish()
-        .execute(aliceClient);
+        .buildAndExecute(aliceClient);
     const aliceDocument = aliceIdentity.didDocument();
 
     // Create a new empty status list. No credentials have been revoked yet.

bindings/wasm/identity_wasm/examples/src/1_advanced/8_zkp.ts

@@ -41,7 +41,7 @@ export async function zkp() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     const issuerDocument = issuerIdentity.didDocument();
 
     // ===========================================================================

bindings/wasm/identity_wasm/examples/src/1_advanced/9_zkp_revocation.ts

@@ -46,7 +46,7 @@ export async function zkp_revocation() {
     const { output: issuerIdentity } = await issuerClient
         .createIdentity(unpublishedIssuerDocument)
         .finish()
-        .execute(issuerClient);
+        .buildAndExecute(issuerClient);
     let issuerDocument = issuerIdentity.didDocument();
 
     // Create an identity for the holder, and publish DID document for it, in this case also the subject.
@@ -56,7 +56,7 @@ export async function zkp_revocation() {
     const { output: holderIdentity } = await holderClient
         .createIdentity(unpublishedholderDocument)
         .finish()
-        .execute(holderClient);
+        .buildAndExecute(holderClient);
     const holderDocument = holderIdentity.didDocument();
 
     // =========================================================================================
@@ -192,10 +192,11 @@ export async function zkp_revocation() {
 
     console.log("Issuer decides to revoke the Credential");
 
+    const issuerIdentityToken = await issuerIdentity.getControllerToken(issuerClient);
     // Update the RevocationBitmap service in the issuer's DID Document.
     // This revokes the credential's unique index.
     issuerDocument.revokeCredentials("my-revocation-service", 5);
-    await issuerIdentity.updateDidDocument(issuerDocument).execute(issuerClient);
+    await issuerIdentity.updateDidDocument(issuerDocument, issuerIdentityToken!).buildAndExecute(issuerClient);
     issuerDocument = issuerIdentity.didDocument();
 
     // Holder checks if his credential has been revoked by the Issuer