@tari-project/tarijs-builders 0.4.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, The Tari Developer Community
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export { buildTransactionRequest, submitAndWaitForTransaction, waitForTransactionResult } from "./submitTransaction";
+export { fromWorkspace, toWorkspace } from "./workspace";

package/dist/helpers/index.js

@@ -0,0 +1,2 @@
+export { buildTransactionRequest, submitAndWaitForTransaction, waitForTransactionResult } from "./submitTransaction";
+export { fromWorkspace, toWorkspace } from "./workspace";

package/dist/helpers/submitTransaction.d.ts

@@ -0,0 +1,10 @@
+import { TariUniverseProvider } from "@tari-project/tari-universe-provider";
+import { TariProvider, SubmitTransactionRequest, SubstateRequirement } from "@tari-project/tari-provider";
+import { Transaction, TransactionResult, DownSubstates, UpSubstates, SubmitTxResult } from "@tari-project/tarijs-types";
+export declare function buildTransactionRequest(transaction: Transaction, accountId: number, requiredSubstates: SubstateRequirement[], inputRefs?: never[], isDryRun?: boolean, network?: number, isSealSignerAuthorized?: boolean, detectInputsUseUnversioned?: boolean): SubmitTransactionRequest;
+export declare function submitAndWaitForTransaction(provider: TariProvider, req: SubmitTransactionRequest): Promise<SubmitTxResult>;
+export declare function waitForTransactionResult(provider: TariProvider | TariUniverseProvider, transactionId: string): Promise<TransactionResult>;
+export declare function getAcceptResultSubstates(txResult: TransactionResult): {
+    upSubstates: UpSubstates;
+    downSubstates: DownSubstates;
+} | undefined;

package/dist/helpers/submitTransaction.js

@@ -0,0 +1,62 @@
+import { TransactionStatus } from "@tari-project/tarijs-types";
+export function buildTransactionRequest(transaction, accountId, requiredSubstates, inputRefs = [], isDryRun = false, network = 0, isSealSignerAuthorized = true, detectInputsUseUnversioned = true) {
+    return {
+        //TODO refactor SubTxReq type to not use 'object[]' and types match
+        // https://github.com/tari-project/tari.js/issues/25
+        network,
+        account_id: accountId,
+        instructions: transaction.instructions,
+        fee_instructions: transaction.feeInstructions,
+        inputs: transaction.inputs,
+        input_refs: inputRefs,
+        required_substates: requiredSubstates,
+        is_dry_run: isDryRun,
+        min_epoch: transaction.minEpoch ?? null,
+        max_epoch: transaction.maxEpoch ?? null,
+        is_seal_signer_authorized: isSealSignerAuthorized,
+        detect_inputs_use_unversioned: detectInputsUseUnversioned,
+    };
+}
+export async function submitAndWaitForTransaction(provider, req) {
+    try {
+        const response = await provider.submitTransaction(req);
+        const result = await waitForTransactionResult(provider, response.transaction_id);
+        return {
+            response,
+            result,
+        };
+    }
+    catch (e) {
+        throw new Error(`Transaction failed: ${e}`);
+    }
+}
+export async function waitForTransactionResult(provider, transactionId) {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const resp = await provider.getTransactionResult(transactionId);
+        const FINALIZED_STATUSES = [
+            TransactionStatus.Accepted,
+            TransactionStatus.Rejected,
+            TransactionStatus.InvalidTransaction,
+            TransactionStatus.OnlyFeeAccepted,
+            TransactionStatus.DryRun,
+        ];
+        if (resp.status == TransactionStatus.Rejected) {
+            throw new Error(`Transaction rejected: ${JSON.stringify(resp.result)}`);
+        }
+        if (FINALIZED_STATUSES.includes(resp.status)) {
+            return resp; //TODO fix: type mismatch (https://github.com/tari-project/tari.js/issues/29)
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+}
+export function getAcceptResultSubstates(txResult) {
+    const result = txResult.result?.result;
+    if (result && isAccept(result)) {
+        return { upSubstates: result.Accept.up_substates, downSubstates: result.Accept.down_substates };
+    }
+    return undefined;
+}
+function isAccept(result) {
+    return "Accept" in result;
+}

package/dist/helpers/workspace.d.ts

@@ -0,0 +1,23 @@
+import { WorkspaceArg } from "@tari-project/tarijs-types";
+/**
+ *
+ * @param key workspace name
+ * @returns encoded Uint8Array value
+ * @example
+ * key: "0"   -> [ 48 ]
+ * key: "0.0" -> [ 48, 46, 48 ]
+ * key: "0.1" -> [ 48, 46, 49 ]
+ *
+ * key: "bucket"   -> [ 98, 117, 99, 107, 101, 116 ]
+ * key: "bucket.0" -> [ 98, 117, 99, 107, 101, 116, 46, 48 ]
+ * key: "bucket.1" -> [ 98, 117, 99, 107, 101, 116, 46, 49 ]
+ */
+export declare function toWorkspace(key: string): number[];
+/**
+ *
+ * @param key workspace name
+ * @returns formatted Workspace data
+ * @example
+ * key: "bucket" -> { Workspace: [ 98, 117, 99, 107, 101, 116 ] }
+ */
+export declare function fromWorkspace(key: string): WorkspaceArg;

package/dist/helpers/workspace.js

@@ -0,0 +1,29 @@
+/**
+ *
+ * @param key workspace name
+ * @returns encoded Uint8Array value
+ * @example
+ * key: "0"   -> [ 48 ]
+ * key: "0.0" -> [ 48, 46, 48 ]
+ * key: "0.1" -> [ 48, 46, 49 ]
+ *
+ * key: "bucket"   -> [ 98, 117, 99, 107, 101, 116 ]
+ * key: "bucket.0" -> [ 98, 117, 99, 107, 101, 116, 46, 48 ]
+ * key: "bucket.1" -> [ 98, 117, 99, 107, 101, 116, 46, 49 ]
+ */
+export function toWorkspace(key) {
+    const encoder = new TextEncoder();
+    return Array.from(encoder.encode(key));
+}
+/**
+ *
+ * @param key workspace name
+ * @returns formatted Workspace data
+ * @example
+ * key: "bucket" -> { Workspace: [ 98, 117, 99, 107, 101, 116 ] }
+ */
+export function fromWorkspace(key) {
+    const encoder = new TextEncoder();
+    const encodedKey = encoder.encode(key);
+    return { Workspace: Array.from(encodedKey) };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "@tari-project/tarijs-types";
+export { TransactionBuilder, TransactionRequest, TariMethodDefinition, TariFunctionDefinition } from "./transaction";
+export { buildTransactionRequest, submitAndWaitForTransaction, waitForTransactionResult, fromWorkspace, toWorkspace, } from "./helpers";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "@tari-project/tarijs-types";
+export { TransactionBuilder, TransactionRequest } from "./transaction";
+export { buildTransactionRequest, submitAndWaitForTransaction, waitForTransactionResult, fromWorkspace, toWorkspace, } from "./helpers";

package/dist/transaction/TransactionBuilder.d.ts

@@ -0,0 +1,86 @@
+import { ComponentAddress, ConfidentialClaim, ConfidentialWithdrawProof, Instruction, ResourceAddress, SubstateRequirement, Transaction, TransactionSignature, UnsignedTransaction, TemplateAddress, Arg } from "@tari-project/tarijs-types";
+export interface TransactionConstructor {
+    new (unsignedTransaction: UnsignedTransaction, signatures: TransactionSignature[]): Transaction;
+}
+export interface TariFunctionDefinition {
+    functionName: string;
+    args?: Arg[];
+    templateAddress: TemplateAddress;
+}
+export interface TariMethodDefinition {
+    methodName: string;
+    args?: Arg[];
+    componentAddress: ComponentAddress;
+}
+export interface TariCreateAccountDefinition {
+    methodName: string;
+    args?: {
+        ownerPublicKey: string;
+        workspaceBucket?: string;
+    };
+}
+export interface Builder {
+    callFunction<T extends TariFunctionDefinition>(func: T, args: Exclude<T["args"], undefined>): this;
+    callMethod<T extends TariMethodDefinition>(method: T, args: Exclude<T["args"], undefined>): this;
+    createAccount(ownerPublicKey: string, workspaceBucket?: string): this;
+    createProof(account: ComponentAddress, resourceAddress: ResourceAddress): this;
+    saveVar(key: string): this;
+    dropAllProofsInWorkspace(): this;
+    claimBurn(claim: ConfidentialClaim): this;
+    addInput(inputObject: SubstateRequirement): this;
+    addInstruction(instruction: Instruction): this;
+    addFeeInstruction(instruction: Instruction): this;
+    withMinEpoch(minEpoch: number): this;
+    withMaxEpoch(maxEpoch: number): this;
+    withInputs(inputs: SubstateRequirement[]): this;
+    withInstructions(instructions: Instruction[]): this;
+    withFeeInstructions(instructions: Instruction[]): this;
+    withFeeInstructionsBuilder(builder: (builder: TransactionBuilder) => this): this;
+    withUnsignedTransaction(unsignedTransaction: UnsignedTransaction): this;
+    feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: string): this;
+    feeTransactionPayFromComponentConfidential(componentAddress: ComponentAddress, proof: ConfidentialWithdrawProof): this;
+    buildUnsignedTransaction(): UnsignedTransaction;
+    build(): Transaction;
+}
+export declare class TransactionBuilder implements Builder {
+    private unsignedTransaction;
+    private signatures;
+    constructor();
+    callFunction<T extends TariFunctionDefinition>(func: T, args: Exclude<T["args"], undefined>): this;
+    callMethod<T extends TariMethodDefinition>(method: T, args: Exclude<T["args"], undefined>): this;
+    createAccount(ownerPublicKey: string, workspaceBucket?: string): this;
+    createProof(account: ComponentAddress, resourceAddress: ResourceAddress): this;
+    claimBurn(claim: ConfidentialClaim): this;
+    /**
+     * The `SaveVar` method replaces
+     * `PutLastInstructionOutputOnWorkspace: { key: Array<number> }`
+     * to make saving variables easier.
+     */
+    saveVar(key: string): this;
+    /**
+     * Adds a fee instruction that calls the `take_fee` method on a component.
+     * This method must exist and return a Bucket with containing revealed confidential XTR resource.
+     * This allows the fee to originate from sources other than the transaction sender's account.
+     * The fee instruction will lock up the `max_fee` amount for the duration of the transaction.
+     */
+    feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: string): this;
+    /**
+     * Adds a fee instruction that calls the `take_fee_confidential` method on a component.
+     * This method must exist and return a Bucket with containing revealed confidential XTR resource.
+     * This allows the fee to originate from sources other than the transaction sender's account.
+     */
+    feeTransactionPayFromComponentConfidential(componentAddress: ComponentAddress, proof: ConfidentialWithdrawProof): this;
+    dropAllProofsInWorkspace(): this;
+    withUnsignedTransaction(unsignedTransaction: UnsignedTransaction): this;
+    withFeeInstructions(instructions: Instruction[]): this;
+    withFeeInstructionsBuilder(builder: (builder: TransactionBuilder) => TransactionBuilder): this;
+    addInstruction(instruction: Instruction): this;
+    addFeeInstruction(instruction: Instruction): this;
+    withInstructions(instructions: Instruction[]): this;
+    addInput(inputObject: SubstateRequirement): this;
+    withInputs(inputs: SubstateRequirement[]): this;
+    withMinEpoch(minEpoch: number): this;
+    withMaxEpoch(maxEpoch: number): this;
+    buildUnsignedTransaction(): UnsignedTransaction;
+    build(): Transaction;
+}

package/dist/transaction/TransactionBuilder.js

@@ -0,0 +1,164 @@
+//   Copyright 2024 The Tari Project
+//   SPDX-License-Identifier: BSD-3-Clause
+import { toWorkspace } from "../helpers";
+import { TransactionRequest } from "./TransactionRequest";
+export class TransactionBuilder {
+    unsignedTransaction;
+    signatures;
+    constructor() {
+        this.unsignedTransaction = {
+            feeInstructions: [],
+            instructions: [],
+            inputs: [],
+            filledInputs: [],
+            minEpoch: undefined,
+            maxEpoch: undefined,
+        };
+        this.signatures = [];
+    }
+    callFunction(func, args) {
+        return this.addInstruction({
+            CallFunction: {
+                template_address: func.templateAddress,
+                function: func.functionName,
+                args,
+            },
+        });
+    }
+    callMethod(method, args) {
+        return this.addInstruction({
+            CallMethod: {
+                component_address: method.componentAddress,
+                method: method.methodName,
+                args,
+            },
+        });
+    }
+    createAccount(ownerPublicKey, workspaceBucket) {
+        return this.addInstruction({
+            CreateAccount: {
+                owner_public_key: ownerPublicKey,
+                workspace_bucket: workspaceBucket ?? null,
+            },
+        });
+    }
+    createProof(account, resourceAddress) {
+        return this.addInstruction({
+            CallMethod: {
+                component_address: account,
+                method: "create_proof_for_resource",
+                args: [resourceAddress],
+            },
+        });
+    }
+    claimBurn(claim) {
+        return this.addInstruction({
+            ClaimBurn: {
+                claim,
+            },
+        });
+    }
+    /**
+     * The `SaveVar` method replaces
+     * `PutLastInstructionOutputOnWorkspace: { key: Array<number> }`
+     * to make saving variables easier.
+     */
+    saveVar(key) {
+        return this.addInstruction({
+            PutLastInstructionOutputOnWorkspace: {
+                key: toWorkspace(key),
+            },
+        });
+    }
+    /**
+     * Adds a fee instruction that calls the `take_fee` method on a component.
+     * This method must exist and return a Bucket with containing revealed confidential XTR resource.
+     * This allows the fee to originate from sources other than the transaction sender's account.
+     * The fee instruction will lock up the `max_fee` amount for the duration of the transaction.
+     */
+    feeTransactionPayFromComponent(componentAddress, maxFee) {
+        return this.addFeeInstruction({
+            CallMethod: {
+                component_address: componentAddress,
+                method: "pay_fee",
+                args: [maxFee],
+            },
+        });
+    }
+    /**
+     * Adds a fee instruction that calls the `take_fee_confidential` method on a component.
+     * This method must exist and return a Bucket with containing revealed confidential XTR resource.
+     * This allows the fee to originate from sources other than the transaction sender's account.
+     */
+    feeTransactionPayFromComponentConfidential(componentAddress, proof) {
+        return this.addFeeInstruction({
+            CallMethod: {
+                component_address: componentAddress,
+                method: "pay_fee_confidential",
+                args: [proof],
+            },
+        });
+    }
+    dropAllProofsInWorkspace() {
+        return this.addInstruction("DropAllProofsInWorkspace");
+    }
+    withUnsignedTransaction(unsignedTransaction) {
+        this.unsignedTransaction = unsignedTransaction;
+        this.signatures = [];
+        return this;
+    }
+    withFeeInstructions(instructions) {
+        this.unsignedTransaction.feeInstructions = instructions;
+        this.signatures = [];
+        return this;
+    }
+    withFeeInstructionsBuilder(builder) {
+        const newBuilder = builder(new TransactionBuilder());
+        this.unsignedTransaction.feeInstructions = newBuilder.unsignedTransaction.instructions;
+        this.signatures = [];
+        return this;
+    }
+    addInstruction(instruction) {
+        this.unsignedTransaction.instructions.push(instruction);
+        this.signatures = [];
+        return this;
+    }
+    addFeeInstruction(instruction) {
+        this.unsignedTransaction.feeInstructions.push(instruction);
+        this.signatures = [];
+        return this;
+    }
+    withInstructions(instructions) {
+        this.unsignedTransaction.instructions.push(...instructions);
+        this.signatures = [];
+        return this;
+    }
+    addInput(inputObject) {
+        this.unsignedTransaction.inputs.push(inputObject);
+        this.signatures = [];
+        return this;
+    }
+    withInputs(inputs) {
+        this.unsignedTransaction.inputs.push(...inputs);
+        this.signatures = [];
+        return this;
+    }
+    withMinEpoch(minEpoch) {
+        this.unsignedTransaction.minEpoch = minEpoch;
+        // Reset the signatures as they are no longer valid
+        this.signatures = [];
+        return this;
+    }
+    withMaxEpoch(maxEpoch) {
+        this.unsignedTransaction.maxEpoch = maxEpoch;
+        // Reset the signatures as they are no longer valid
+        this.signatures = [];
+        return this;
+    }
+    buildUnsignedTransaction() {
+        return this.unsignedTransaction;
+    }
+    build() {
+        return new TransactionRequest(this.unsignedTransaction, this.signatures);
+    }
+}

package/dist/transaction/TransactionRequest.d.ts

@@ -0,0 +1,27 @@
+import { Epoch, Instruction, SubstateRequirement, Transaction, TransactionId, TransactionSignature, UnsignedTransaction, VersionedSubstateId } from "@tari-project/tarijs-types";
+export declare class TransactionRequest implements Transaction {
+    id: TransactionId;
+    feeInstructions: Array<Instruction>;
+    instructions: Array<Instruction>;
+    inputs: Array<SubstateRequirement>;
+    signatures: Array<TransactionSignature>;
+    unsignedTransaction: UnsignedTransaction;
+    minEpoch?: Epoch;
+    maxEpoch?: Epoch;
+    filledInputs: VersionedSubstateId[];
+    constructor(unsignedTransaction: UnsignedTransaction, signatures: TransactionSignature[]);
+    private calculateHash;
+    withFilledInputs(filled_inputs: Array<VersionedSubstateId>): this;
+    getId(): TransactionId;
+    checkId(): boolean;
+    getUnsignedTransaction(): UnsignedTransaction;
+    getFeeInstructions(): Instruction[];
+    getInstructions(): Instruction[];
+    getSignatures(): TransactionSignature[];
+    getHash(): string;
+    getInputs(): SubstateRequirement[];
+    getFilledInputs(): VersionedSubstateId[];
+    getFilledInputsMut(): VersionedSubstateId[];
+    getMinEpoch(): Epoch | undefined;
+    getMaxEpoch(): Epoch | undefined;
+}

package/dist/transaction/TransactionRequest.js

@@ -0,0 +1,67 @@
+///TODO this implementation is not fully done, see:
+/// https://github.com/tari-project/tari-dan/blob/development/dan_layer/transaction/src/transaction.rs
+export class TransactionRequest {
+    id;
+    feeInstructions;
+    instructions;
+    inputs;
+    signatures;
+    unsignedTransaction;
+    minEpoch;
+    maxEpoch;
+    filledInputs;
+    constructor(unsignedTransaction, signatures) {
+        this.id = this.calculateHash();
+        this.feeInstructions = unsignedTransaction.feeInstructions;
+        this.instructions = unsignedTransaction.instructions;
+        this.inputs = unsignedTransaction.inputs;
+        this.signatures = signatures;
+        this.minEpoch = unsignedTransaction.minEpoch;
+        this.maxEpoch = unsignedTransaction.maxEpoch;
+        // Inputs filled by some authority. These are not part of the transaction hash nor the signature
+        this.filledInputs = [];
+    }
+    calculateHash() {
+        return "";
+    }
+    withFilledInputs(filled_inputs) {
+        return { ...this, filled_inputs };
+    }
+    getId() {
+        return this.id;
+    }
+    checkId() {
+        const id = this.calculateHash();
+        return id === this.id;
+    }
+    getUnsignedTransaction() {
+        return this.unsignedTransaction;
+    }
+    getFeeInstructions() {
+        return this.feeInstructions;
+    }
+    getInstructions() {
+        return this.instructions;
+    }
+    getSignatures() {
+        return this.signatures;
+    }
+    getHash() {
+        return this.id;
+    }
+    getInputs() {
+        return this.inputs;
+    }
+    getFilledInputs() {
+        return this.filledInputs;
+    }
+    getFilledInputsMut() {
+        return this.filledInputs;
+    }
+    getMinEpoch() {
+        return this.minEpoch;
+    }
+    getMaxEpoch() {
+        return this.maxEpoch;
+    }
+}

package/dist/transaction/index.d.ts

@@ -0,0 +1,2 @@
+export { TransactionBuilder, TariMethodDefinition, TariFunctionDefinition } from "./TransactionBuilder";
+export { TransactionRequest } from "./TransactionRequest";

package/dist/transaction/index.js

@@ -0,0 +1,2 @@
+export { TransactionBuilder } from "./TransactionBuilder";
+export { TransactionRequest } from "./TransactionRequest";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tari-project/tarijs-builders",
+  "version": "0.4.0",
+  "description": "",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@tari-project/typescript-bindings": "^1.4.0",
+    "@tari-project/tari-universe-provider": "^0.4.0",
+    "@tari-project/tari-provider": "^0.4.0",
+    "@tari-project/tarijs-types": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "typescript": "^5.0.4"
+  },
+  "files": [
+    "/dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b"
+  }
+}