@layerzerolabs/lz-iotal1-sdk-v2 3.0.143

package/src/utils/non-sender-object-validator.ts

@@ -0,0 +1,102 @@
+import { ObjectOwner } from '@iota/iota-sdk/client'
+
+import { MoveCallWithObjectDetails } from './move-call-object-fetcher'
+import { IPTBValidator } from './ptb-validator'
+
+/**
+ * NonSenderObjectValidator ensures objects are not owned by the transaction sender
+ *
+ * In Iota, this validator checks that objects are:
+ * - Shared: globally accessible, mutations require consensus
+ * - Immutable: can't change after creation
+ * - Owned by another address (not the sender)
+ *
+ * This prevents the sender from using their own owned objects in the transaction
+ */
+export class NonSenderObjectValidator implements IPTBValidator {
+    private sender: string
+
+    constructor(sender: string) {
+        this.sender = sender
+    }
+
+    /**
+     * Validates that objects are not owned by the sender
+     * @param moveCallsWithDetails - Array of move calls with object details
+     * @throws Error if any object is owned by the sender
+     */
+    validate(moveCallsWithDetails: MoveCallWithObjectDetails[]): void {
+        for (const { objectDetails } of moveCallsWithDetails) {
+            for (const [objectId, objectResponse] of objectDetails) {
+                const owner = objectResponse.data?.owner
+                if (owner == null) {
+                    throw new Error(`Object ${objectId} has no owner`)
+                }
+                // Validate that object is not owned by the sender
+                if (!this.isValidOwnership(owner)) {
+                    const ownerType = this.getOwnershipType(owner)
+                    throw new Error(
+                        `Object ${objectId} is owned by the sender (${this.sender}). ` +
+                            `Only Shared, Immutable, or objects owned by other addresses are allowed. ` +
+                            `Current ownership: ${ownerType}`
+                    )
+                }
+            }
+        }
+    }
+
+    /**
+     * Checks if the ownership is valid (not owned by sender)
+     * @param owner - The object owner to check
+     * @returns true if ownership is valid (Shared, Immutable, or owned by another address)
+     */
+    private isValidOwnership(owner: ObjectOwner): boolean {
+        // Shared objects are valid
+        if (typeof owner === 'object' && 'Shared' in owner) {
+            return true
+        }
+
+        // Immutable objects are valid
+        if (owner === 'Immutable') {
+            return true
+        }
+
+        // Objects owned by another address are valid
+        if (typeof owner === 'object' && 'AddressOwner' in owner && owner.AddressOwner !== this.sender) {
+            return true
+        }
+
+        // Objects owned by another object are valid
+        if (typeof owner === 'object' && 'ObjectOwner' in owner) {
+            return true
+        }
+
+        // If owned by sender, it's invalid
+        return false
+    }
+
+    /**
+     * Gets a human-readable description of the ownership type
+     * @param owner - The object owner
+     * @returns String description of ownership type
+     */
+    private getOwnershipType(owner: ObjectOwner): string {
+        if (typeof owner === 'object' && 'Shared' in owner) {
+            return `Shared (initial_shared_version: ${owner.Shared.initial_shared_version})`
+        }
+
+        if (owner === 'Immutable') {
+            return 'Immutable'
+        }
+
+        if (typeof owner === 'object' && 'AddressOwner' in owner) {
+            return `AddressOwner: ${owner.AddressOwner}`
+        }
+
+        if (typeof owner === 'object' && 'ObjectOwner' in owner) {
+            return `ObjectOwner: ${owner.ObjectOwner}`
+        }
+
+        return 'Unknown ownership type'
+    }
+}

package/src/utils/package-allowlist-validator.ts

@@ -0,0 +1,134 @@
+import { MoveCallWithObjectDetails } from './move-call-object-fetcher'
+import { IPTBValidator } from './ptb-validator'
+import { PackageWhitelistValidator as PackageWhitelistSDK } from '../modules/ptb-builders/package-whitelist-validator'
+
+/**
+ * PackageAllowlistValidator ensures all function calls and objects belong to allowlisted packages
+ * This validator checks that:
+ * 1. All function calls target approved packages
+ * 2. All object arguments come from approved packages
+ *
+ * If local packageWhitelist is empty, it will use the PTB whitelist contract for validation
+ * If local packageWhitelist is provided, it will use only the local whitelist (contract is ignored)
+ */
+export class PackageAllowlistValidator implements IPTBValidator {
+    private packageWhitelist: Set<string>
+    private validator?: PackageWhitelistSDK
+
+    constructor(packageWhitelist: string[] = [], validator?: PackageWhitelistSDK) {
+        if (packageWhitelist.length == 0 && validator == null) {
+            throw new Error('PackageAllowlistValidator requires either a packageWhitelist or a validator')
+        }
+        this.packageWhitelist = new Set(packageWhitelist)
+        this.validator = validator
+    }
+
+    /**
+     * Validates that all function calls and object arguments belong to whitelisted packages
+     * @param moveCallsWithDetails - Array of move calls with object details
+     * @throws Error if any function call or object belongs to a non-whitelisted package
+     */
+    async validate(moveCallsWithDetails: MoveCallWithObjectDetails[]): Promise<void> {
+        const allPackages = new Set<string>()
+
+        // Collect packages from function calls
+        for (const { moveCall } of moveCallsWithDetails) {
+            const packageId = moveCall.function.package
+            if (packageId === '') {
+                throw new Error('Move call package is missing')
+            }
+            allPackages.add(packageId)
+        }
+
+        // Collect packages from objects
+        for (const { objectDetails } of moveCallsWithDetails) {
+            for (const [objectId, objectResponse] of objectDetails) {
+                if (!objectResponse.data) {
+                    throw new Error(`Object ${objectId} not found`)
+                }
+
+                const packageId = this.extractPackageIdFromType(objectResponse.data.type)
+                if (packageId == null) {
+                    throw new Error(`Could not extract package ID from object ${objectId}`)
+                }
+                allPackages.add(packageId)
+            }
+        }
+
+        // Validate all packages at once
+        const isAllValid = await this.validatePackages(Array.from(allPackages))
+        // Check result - if any package failed, throw error
+        if (!isAllValid) {
+            throw new Error(
+                `One or more packages are not allowlisted. Packages: [${Array.from(allPackages).join(', ')}]`
+            )
+        }
+    }
+
+    /**
+     * Validate multiple packages at once
+     * @param packages - Array of package IDs to validate
+     * @returns Object mapping package ID to validation result
+     */
+    private async validatePackages(packages: string[]): Promise<boolean> {
+        if (packages.length === 0) {
+            return true
+        }
+        // If custom whitelist is provided, use it first
+        if (this.packageWhitelist.size > 0) {
+            // Check if ALL packages are in whitelist - if any fails, return false
+            for (const packageId of packages) {
+                if (!this.packageWhitelist.has(packageId)) {
+                    return false
+                }
+            }
+            return true
+        } else {
+            // Use the contract's validate function to validate all packages at once
+            try {
+                return await this.validator!.validate(packages)
+            } catch (error) {
+                console.warn(`Failed to check whitelist:`, error)
+                return false
+            }
+        }
+    }
+
+    /**
+     * Extracts package ID from object type string
+     * Object types are in format: "packageId::module::struct<generics>"
+     * @param objectType - The object type string
+     * @returns The package ID or null if extraction fails
+     */
+    private extractPackageIdFromType(objectType: string | null | undefined): string | null {
+        if (objectType == null) {
+            return null
+        }
+
+        // Object type format: "0x123abc::module_name::struct_name<T1, T2>"
+        // We want to extract the package ID (0x123abc)
+        const parts = objectType.split('::')
+        if (parts.length < 2) {
+            return null
+        }
+
+        const packageId = parts[0]
+
+        // Validate that it looks like a package ID (starts with 0x and has hex characters)
+        if (!packageId.startsWith('0x') || packageId.length < 3) {
+            return null
+        }
+
+        return packageId
+    }
+
+    /**
+     * Get available packages for error messages
+     */
+    private getAvailablePackagesList(): string {
+        if (this.packageWhitelist.size > 0) {
+            return Array.from(this.packageWhitelist).join(', ')
+        }
+        return 'contract whitelist'
+    }
+}

package/src/utils/ptb-validator.ts

@@ -0,0 +1,14 @@
+import { MoveCallWithObjectDetails } from './move-call-object-fetcher'
+
+export interface ObjectFetchOptions {
+    showOwner?: boolean
+    showType?: boolean
+    showContent?: boolean
+    showBcs?: boolean
+    showDisplay?: boolean
+    showStorageRebate?: boolean
+}
+
+export interface IPTBValidator {
+    validate(moveCallsWithDetails: MoveCallWithObjectDetails[], sender?: string): void | Promise<void>
+}

package/src/utils/share-object-validator.ts

@@ -0,0 +1,37 @@
+import { ObjectOwner } from '@iota/iota-sdk/client'
+
+import { MoveCallWithObjectDetails } from './move-call-object-fetcher'
+import { IPTBValidator } from './ptb-validator'
+
+/**
+ * ShareObjectValidator ensures all object arguments are Shared or Immutable
+ * This is the default validator for PTB operations
+ */
+export class ShareObjectValidator implements IPTBValidator {
+    /**
+     * Validates move calls with pre-fetched object details
+     * @param moveCallsWithDetails - Array of move calls with object details
+     * @throws Error if any object is not Shared/Immutable
+     */
+    validate(moveCallsWithDetails: MoveCallWithObjectDetails[]): void {
+        for (const { objectDetails } of moveCallsWithDetails) {
+            for (const [objectId, objectResponse] of objectDetails) {
+                if (objectResponse.data?.owner == null) {
+                    throw new Error(`Object ${objectId} does not have owner`)
+                }
+                if (!this.isSharedOrImmutable(objectResponse.data.owner)) {
+                    throw new Error(`Object ${objectId} is not Shared/Immutable`)
+                }
+            }
+        }
+    }
+
+    /**
+     * Checks if an object owner is Shared or Immutable
+     * @param owner - The object owner to check
+     * @returns true if the owner is Shared or Immutable, false otherwise
+     */
+    protected isSharedOrImmutable(owner: ObjectOwner): boolean {
+        return (typeof owner === 'object' && 'Shared' in owner) || owner === 'Immutable'
+    }
+}

package/src/utils/transaction.ts

@@ -0,0 +1,157 @@
+import { IotaClient, IotaExecutionResult, IotaTransactionBlockResponse } from '@iota/iota-sdk/client'
+import { Keypair } from '@iota/iota-sdk/cryptography'
+import { Ed25519Keypair } from '@iota/iota-sdk/keypairs/ed25519'
+import { Transaction } from '@iota/iota-sdk/transactions'
+import { fromBase64 } from '@iota/iota-sdk/utils'
+
+import { MoveAbortError, SimulateResult, UnclassifiedError } from '../types'
+
+export async function simulateTransaction(
+    iotaClient: IotaClient,
+    tx: Transaction,
+    sender?: string
+): Promise<SimulateResult[]> {
+    const resolvedSender = determineSenderAddress(tx, sender)
+    const { results, error } = await iotaClient.devInspectTransactionBlock({
+        transactionBlock: tx,
+        sender: resolvedSender,
+    })
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (error != undefined && error != null) {
+        throw handleError(error)
+    }
+    if (results === undefined || results === null) {
+        throw new Error('No results found')
+    }
+    const lastCommandResults: IotaExecutionResult = results[results.length - 1]
+
+    if (lastCommandResults.returnValues === undefined) {
+        throw new Error('No return values found')
+    }
+    return lastCommandResults.returnValues.map((result) => {
+        return {
+            value: typeof result[0] === 'string' ? fromBase64(result[0]) : new Uint8Array(result[0]),
+            type: result[1],
+        }
+    })
+}
+
+export async function simulateTransactionMultiResult(
+    iotaClient: IotaClient,
+    tx: Transaction,
+    resultIndex: number[],
+    sender?: string
+): Promise<SimulateResult[][]> {
+    const resolvedSender = determineSenderAddress(tx, sender)
+    const { results, error } = await iotaClient.devInspectTransactionBlock({
+        transactionBlock: tx,
+        sender: resolvedSender,
+    })
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (error != undefined && error != null) {
+        throw handleError(error)
+    }
+    if (results === undefined || results === null) {
+        throw new Error('No results found')
+    }
+
+    const selectedResults: IotaExecutionResult[] = resultIndex.map((idx) => {
+        return results[idx]
+    })
+
+    return selectedResults.map((result) => {
+        if (result.returnValues === undefined) {
+            throw new Error('No return values found')
+        }
+        return result.returnValues.map((result) => {
+            return {
+                value: typeof result[0] === 'string' ? fromBase64(result[0]) : new Uint8Array(result[0]),
+                type: result[1],
+            }
+        })
+    })
+}
+
+export async function validateTransaction(
+    client: IotaClient,
+    signer: Keypair,
+    tx: Transaction
+): Promise<IotaTransactionBlockResponse> {
+    tx.setSenderIfNotSet(signer.getPublicKey().toIotaAddress())
+    const result = await client.signAndExecuteTransaction({
+        signer,
+        transaction: tx,
+        options: {
+            showEffects: true,
+            showObjectChanges: true,
+            showEvents: true,
+        },
+    })
+
+    if (result.effects?.status.status !== 'success') {
+        throw new Error(result.effects?.status.error)
+    }
+
+    await client.waitForTransaction({ digest: result.digest })
+    return result
+}
+
+/**
+ * Execute simulate using a moveCall function
+ * @param client - The Iota client
+ * @param moveCallFn - Function that adds moveCall to the transaction (supports both sync and async, any return type)
+ * @param parser - Function to parse the result
+ * @returns The parsed result
+ */
+export async function executeSimulate<T>(
+    client: IotaClient,
+    moveCallFn: (tx: Transaction) => unknown,
+    parser: (result: { value: Uint8Array }[]) => T
+): Promise<T> {
+    const tx = new Transaction()
+    await moveCallFn(tx)
+    const result = await simulateTransaction(client, tx)
+    return parser(result)
+}
+
+/**
+ * Determines the appropriate sender address using fallback hierarchy:
+ * 1. Use provided sender if available
+ * 2. Use transaction's existing sender if valid
+ * 3. Generate a random sender as last resort
+ *
+ * @param tx - The transaction to get sender from
+ * @param preferredSender - Optional sender address to prioritize
+ * @returns The determined sender address
+ */
+function determineSenderAddress(tx: Transaction, preferredSender?: string): string {
+    //eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    if (preferredSender) return preferredSender
+
+    const existingSender = tx.getData().sender
+    if (typeof existingSender === 'string') return existingSender
+
+    return Ed25519Keypair.generate().toIotaAddress()
+}
+
+export function handleError(e: string): unknown {
+    if (e.includes('ExecutionError')) {
+        const majorStatusMatch = e.match(/major_status:\s([A-Z_]+)/)
+        if (majorStatusMatch !== null) {
+            const major_status = majorStatusMatch[1]
+            if (major_status === 'ABORTED') {
+                const subStatusMatch = e.match(/sub_status:\sSome\((\d+)\)/)
+                if (subStatusMatch === null) {
+                    return new MoveAbortError(Number.NEGATIVE_INFINITY, e)
+                } else {
+                    return new MoveAbortError(Number(subStatusMatch[1]), e)
+                }
+            }
+        } else {
+            return new UnclassifiedError(e)
+        }
+    }
+    return new Error(e)
+}

package/src/utils/type-name.ts

@@ -0,0 +1,99 @@
+import sha3 from 'js-sha3'
+
+import { ModuleManager } from '../module-manager'
+import { CallTypeName, LzTypeName, Modules } from '../types'
+
+// Predefined type names
+const TYPE_CONFIG = {
+    [LzTypeName.EndpointQuoteParam]: { pkg: Modules.Endpoint, module: 'endpoint_quote', type: 'QuoteParam' },
+    [LzTypeName.EndpointSendParam]: { pkg: Modules.Endpoint, module: 'endpoint_send', type: 'SendParam' },
+    [LzTypeName.MessageLibQuoteParam]: { pkg: Modules.Endpoint, module: 'message_lib_quote', type: 'QuoteParam' },
+    [LzTypeName.MessageLibSendParam]: { pkg: Modules.Endpoint, module: 'message_lib_send', type: 'SendParam' },
+    [LzTypeName.MessageLibSendResult]: { pkg: Modules.Endpoint, module: 'message_lib_send', type: 'SendResult' },
+    [LzTypeName.MessageLibSetConfigParam]: {
+        pkg: Modules.Endpoint,
+        module: 'message_lib_set_config',
+        type: 'SetConfigParam',
+    },
+    [LzTypeName.MessagingFee]: { pkg: Modules.Endpoint, module: 'messaging_fee', type: 'MessagingFee' },
+    [LzTypeName.MessagingReceipt]: { pkg: Modules.Endpoint, module: 'messaging_receipt', type: 'MessagingReceipt' },
+    [LzTypeName.EndpointLzReceiveParam]: { pkg: Modules.Endpoint, module: 'lz_receive', type: 'LzReceiveParam' },
+    [LzTypeName.EndpointLzComposeParam]: { pkg: Modules.Endpoint, module: 'lz_compose', type: 'LzComposeParam' },
+    [LzTypeName.MoveCall]: { pkg: Modules.Call, module: 'move_call', type: 'MoveCall' },
+    [LzTypeName.CallVoid]: { pkg: Modules.Call, module: 'call', type: 'Void' },
+} as const
+
+// Call type configuration
+const CALL_TYPE_CONFIG = {
+    [CallTypeName.EndpointQuoteCall]: { param: LzTypeName.EndpointQuoteParam, result: LzTypeName.MessagingFee },
+    [CallTypeName.EndpointSendCall]: { param: LzTypeName.EndpointSendParam, result: LzTypeName.MessagingReceipt },
+    [CallTypeName.MessageLibQuoteCall]: { param: LzTypeName.MessageLibQuoteParam, result: LzTypeName.MessagingFee },
+    [CallTypeName.MessageLibSendCall]: {
+        param: LzTypeName.MessageLibSendParam,
+        result: LzTypeName.MessageLibSendResult,
+    },
+    [CallTypeName.MessageLibSetConfigCall]: { param: LzTypeName.MessageLibSetConfigParam, result: LzTypeName.CallVoid },
+    [CallTypeName.EndpointLzReceiveCall]: { param: LzTypeName.EndpointLzReceiveParam, result: LzTypeName.CallVoid },
+    [CallTypeName.EndpointLzComposeCall]: { param: LzTypeName.EndpointLzComposeParam, result: LzTypeName.CallVoid },
+} as const
+
+export function getTypeName(moduleManager: ModuleManager, type: LzTypeName | CallTypeName): string {
+    // Handle simple types
+    if (type in TYPE_CONFIG) {
+        const config = TYPE_CONFIG[type as keyof typeof TYPE_CONFIG]
+        const { packageId } = moduleManager.getModule<{ packageId: string }>(config.pkg)
+        return buildTypeName(packageId, config.module, config.type)
+    }
+
+    // Handle Call types
+    if (type in CALL_TYPE_CONFIG) {
+        const callConfig = CALL_TYPE_CONFIG[type as keyof typeof CALL_TYPE_CONFIG]
+        const paramType = getTypeName(moduleManager, callConfig.param)
+        const resultType = getTypeName(moduleManager, callConfig.result)
+        return buildCallTypeName(moduleManager.getCall().packageId, paramType, resultType)
+    }
+
+    throw new Error(`Unknown type name: ${JSON.stringify(type)}`)
+}
+
+/**
+ * Normalizes a Iota package ID with configurable formatting options
+ * @param packageId - The package ID to normalize (with or without 0x prefix)
+ * @param includePrefix - Whether to include the '0x' prefix in the result (default: false)
+ * @param trimLeadingZeros - Whether to remove leading zeros (default: true)
+ * @returns The normalized package ID
+ *
+ * @example
+ * normalizeIotaPackageId('0x0001abc', false, true) // '1abc'
+ * normalizeIotaPackageId('0x0001abc', true, true) // '0x1abc'
+ * normalizeIotaPackageId('0x0001abc', true, false) // '0x0001abc'
+ */
+export function normalizeIotaPackageId(packageId: string, includePrefix = false, trimLeadingZeros = false): string {
+    // Remove 0x prefix if present
+    let normalized = packageId.startsWith('0x') ? packageId.slice(2) : packageId
+
+    // Trim leading zeros if requested
+    if (trimLeadingZeros) {
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        normalized = normalized.replace(/^0+/, '') || '0'
+    }
+
+    // Add prefix back if requested
+    return includePrefix ? `0x${normalized}` : normalized
+}
+
+export function callId(moduleManager: ModuleManager, type: CallTypeName): string {
+    return sha3.keccak_256(Buffer.from(getTypeName(moduleManager, type)))
+}
+
+// === Internal Functions ===
+
+// Helper function: build basic type name
+function buildTypeName(packageId: string, module: string, type: string): string {
+    return `${normalizeIotaPackageId(packageId)}::${module}::${type}`
+}
+
+// Helper function: build Call type name
+function buildCallTypeName(packageId: string, paramType: string, resultType: string): string {
+    return `${normalizeIotaPackageId(packageId)}::call::Call<${paramType},${resultType}>`
+}

package/src/utils/validate-with-details.ts

@@ -0,0 +1,50 @@
+import { IotaClient } from '@iota/iota-sdk/client'
+
+import { MoveCallObjectFetcher } from './move-call-object-fetcher'
+import { IPTBValidator, ObjectFetchOptions } from './ptb-validator'
+import { MAX_BATCH_SIZE, MoveCall } from '../types'
+
+/**
+ * Validates move calls using multiple validators with a single object fetch
+ * @param client - IotaClient instance
+ * @param moveCalls - Array of move calls to validate
+ * @param validators - Array of validators to run
+ * @param options - Options for what object data to fetch
+ * @param batchSize - Batch size for object fetching
+ */
+export async function validateWithDetails(
+    client: IotaClient,
+    moveCalls: MoveCall[],
+    validators: IPTBValidator[],
+    sender?: string,
+    userOptions: ObjectFetchOptions = {},
+    batchSize: number = MAX_BATCH_SIZE
+): Promise<void> {
+    if (validators.length === 0) {
+        return // No validators to run
+    }
+
+    // Default to fetching all common options, user can override
+    const defaultOptions: ObjectFetchOptions = {
+        showOwner: true,
+        showType: true,
+        showContent: false,
+        showBcs: false,
+        showDisplay: false,
+        showStorageRebate: false,
+    }
+
+    // Merge user options with defaults (user options take precedence)
+    const finalOptions = { ...defaultOptions, ...userOptions }
+
+    // Fetch object details once
+    const objectFetcher = new MoveCallObjectFetcher(client, batchSize)
+    const moveCallsWithDetails = await objectFetcher.fetchObjectDetails(moveCalls, finalOptions)
+    // Run all validators with the same object details
+    for (const validator of validators) {
+        const result = validator.validate(moveCallsWithDetails, sender)
+        if (result instanceof Promise) {
+            await result
+        }
+    }
+}