@usearete/sdk 0.13.0 → 0.15.0

package/dist/index.cjs

@@ -3123,6 +3123,195 @@ function createTypedViews(stack, storage, subscriptionRegistry) {
     return views;
 }
 
+/**
+ * Wallet adapter boundary for the Arete SDK.
+ *
+ * The core SDK is intentionally RPC-free: it only constructs `BuiltInstruction`
+ * objects. Everything network-related (recent blockhash, message compilation,
+ * signing, sending, and confirmation) lives behind the `WalletAdapter`
+ * boundary, implemented by adapters that wrap the Solana library of your choice
+ * (@solana/web3.js, @solana/kit, a raw Keypair signer for scripts, etc.).
+ */
+/** Canonical resource option keys, in contract order. */
+const TRANSACTION_RESOURCE_OPTION_KEYS = [
+    'computeUnitLimit',
+    'loadedAccountsDataSizeLimit',
+    'heapSize',
+    'priorityFeeLamports',
+    'computeUnitPriceMicroLamports',
+];
+/** Typed rejection for malformed or unsupported build options. */
+class TransactionOptionsError extends Error {
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'TransactionOptionsError';
+        this.code = code;
+        this.option = details.option;
+        this.requestedVersion = details.requestedVersion;
+        this.supportedVersions = details.supportedVersions;
+    }
+}
+const U32_MAX = 0xffffffffn;
+const U64_MAX = (1n << 64n) - 1n;
+const DECIMAL = /^\d+$/;
+function inRange(value, max, option) {
+    if (value > max) {
+        throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' exceeds its maximum of ${max}`, { option });
+    }
+    return value;
+}
+function parseUnits(value, option) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'bigint') {
+        if (value < 0n) {
+            throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must not be negative`, { option });
+        }
+        return inRange(value, U32_MAX, option);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must be a non-negative integer or decimal string, `
+                + `received ${value}`, { option });
+        }
+        return inRange(BigInt(value), U32_MAX, option);
+    }
+    if (typeof value === 'string' && DECIMAL.test(value)) {
+        return inRange(BigInt(value), U32_MAX, option);
+    }
+    throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must be a non-negative integer or decimal string`, { option });
+}
+function parseLamports(value, option) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number') {
+        throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must be a bigint or decimal string, never a number: `
+            + 'every JavaScript number is a double, so a u64 passed as one may already have lost '
+            + `precision before it reached the SDK (received ${value})`, { option });
+    }
+    if (typeof value === 'bigint') {
+        if (value < 0n) {
+            throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must not be negative`, { option });
+        }
+        return inRange(value, U64_MAX, option);
+    }
+    if (typeof value === 'string' && DECIMAL.test(value)) {
+        return inRange(BigInt(value), U64_MAX, option);
+    }
+    throw new TransactionOptionsError('invalid_transaction_option', `Transaction option '${option}' must be a bigint or decimal string`, { option });
+}
+/**
+ * Merge execution defaults with per-call send options.
+ *
+ * `resources` merges key by key, so a per-call fee does not discard a
+ * configured compute budget — except for the two fee fields, which are one
+ * slot: setting either clears the other, or the merged budget would hold both
+ * and be refused as mutually exclusive. Shared by every entry point that has
+ * defaults to merge; duplicating this logic is how `session` came to disagree
+ * with `Arete.execute`.
+ */
+function mergeSendOptions(defaults, override) {
+    if (!defaults)
+        return override;
+    if (!override)
+        return defaults;
+    const inherited = { ...defaults.resources };
+    if (override.resources?.priorityFeeLamports !== undefined ||
+        override.resources?.computeUnitPriceMicroLamports !== undefined) {
+        delete inherited.priorityFeeLamports;
+        delete inherited.computeUnitPriceMicroLamports;
+    }
+    const resources = defaults.resources || override.resources
+        ? { ...inherited, ...override.resources }
+        : undefined;
+    return { ...defaults, ...override, ...(resources ? { resources } : {}) };
+}
+/**
+ * Validate build options against an adapter's declared capability and
+ * normalize every quantity to a bigint.
+ *
+ * Rejections are never silent downgrades: an explicit version the adapter does
+ * not advertise fails, and a fee field used against the wrong version fails
+ * instead of being converted.
+ */
+function resolveTransactionBuildOptions(options, capability) {
+    const requested = options?.transactionVersion;
+    if (requested !== undefined && requested !== 'legacy' && requested !== 0 && requested !== 1) {
+        throw new TransactionOptionsError('invalid_transaction_option', `Unknown transactionVersion ${JSON.stringify(requested)}: expected 'legacy', 0, or 1`, { option: 'transactionVersion' });
+    }
+    const supported = capability?.supportedTransactionVersions;
+    if (requested !== undefined) {
+        // Undeclared capability means unknown, not unsupported: old versions keep
+        // working, and only an explicit V1 request needs proof of support.
+        const unsupported = supported ? !supported.includes(requested) : requested === 1;
+        if (unsupported) {
+            throw new TransactionOptionsError('unsupported_transaction_version', `Wallet adapter does not support transaction version ${JSON.stringify(requested)}`
+                + (supported
+                    ? ` (supported: ${supported.map((version) => JSON.stringify(version)).join(', ')})`
+                    : ' (adapter declares no supported versions)'), { option: 'transactionVersion', requestedVersion: requested, supportedVersions: supported });
+        }
+    }
+    const resources = options?.resources;
+    if (resources !== undefined) {
+        if (typeof resources !== 'object' || resources === null || Array.isArray(resources)) {
+            throw new TransactionOptionsError('invalid_transaction_option', 'Transaction option \'resources\' must be an object of canonical resource options', { option: 'resources' });
+        }
+        // Closed key set: an unrecognized budget key is a rejection, never a
+        // silently ignored passthrough.
+        const unknownKey = Object.keys(resources).find((key) => !TRANSACTION_RESOURCE_OPTION_KEYS.includes(key));
+        if (unknownKey) {
+            throw new TransactionOptionsError('unsupported_resource_option', `Unknown resource option '${unknownKey}': expected one of `
+                + TRANSACTION_RESOURCE_OPTION_KEYS.join(', '), { option: unknownKey });
+        }
+    }
+    const honoured = capability?.supportedResourceOptions;
+    if (honoured) {
+        const rejected = TRANSACTION_RESOURCE_OPTION_KEYS.find((key) => resources?.[key] !== undefined && !honoured.includes(key));
+        if (rejected) {
+            throw new TransactionOptionsError('unsupported_resource_option', `Wallet adapter does not apply the '${rejected}' resource option`, { option: rejected });
+        }
+    }
+    const version = requested ?? 0;
+    if (resources?.priorityFeeLamports !== undefined
+        && resources?.computeUnitPriceMicroLamports !== undefined) {
+        throw new TransactionOptionsError('invalid_transaction_option', 'priorityFeeLamports and computeUnitPriceMicroLamports are mutually exclusive', { option: 'priorityFeeLamports', requestedVersion: version });
+    }
+    if (resources?.priorityFeeLamports !== undefined && version !== 1) {
+        throw new TransactionOptionsError('unsupported_resource_option', `priorityFeeLamports requires transaction version 1, not ${JSON.stringify(version)}`, { option: 'priorityFeeLamports', requestedVersion: version });
+    }
+    if (resources?.computeUnitPriceMicroLamports !== undefined && version === 1) {
+        throw new TransactionOptionsError('unsupported_resource_option', 'computeUnitPriceMicroLamports applies to legacy/v0 only; version 1 uses priorityFeeLamports', { option: 'computeUnitPriceMicroLamports', requestedVersion: version });
+    }
+    return {
+        transactionVersion: version,
+        resources: {
+            computeUnitLimit: parseUnits(resources?.computeUnitLimit, 'computeUnitLimit'),
+            loadedAccountsDataSizeLimit: parseUnits(resources?.loadedAccountsDataSizeLimit, 'loadedAccountsDataSizeLimit'),
+            heapSize: parseUnits(resources?.heapSize, 'heapSize'),
+            priorityFeeLamports: parseLamports(resources?.priorityFeeLamports, 'priorityFeeLamports'),
+            computeUnitPriceMicroLamports: parseLamports(resources?.computeUnitPriceMicroLamports, 'computeUnitPriceMicroLamports'),
+        },
+    };
+}
+/**
+ * Boundary form of a resolved resource budget: flat canonical camelCase keys,
+ * every present value a decimal string, absent keys omitted.
+ *
+ * Mirrors Rust `TransactionResourceOptions::to_json()` and Python `to_wire()`.
+ * Key order is not part of the contract (Rust sorts, Python uses declaration
+ * order); the keys and their decimal-string values are. bigint stays the
+ * in-process type; `JSON.stringify` cannot emit one.
+ */
+function toWireResourceOptions(resources) {
+    const wire = {};
+    for (const key of TRANSACTION_RESOURCE_OPTION_KEYS) {
+        const value = resources[key];
+        if (value !== undefined)
+            wire[key] = value.toString(10);
+    }
+    return wire;
+}
+
 /**
  * Non-enumerable brand attached by the operation and read factories so
  * tooling (e.g. the knowledge-layer extractor's runtime walk) can classify
@@ -3473,6 +3662,7 @@ function createTransactionTransport(baseUrl, authenticatedFetch) {
                 err: value.err ?? null,
                 logs: value.logs ?? null,
                 unitsConsumed: optionalBigint(value.unitsConsumed, 'unitsConsumed'),
+                loadedAccountsDataSize: optionalBigint(value.loadedAccountsDataSize, 'loadedAccountsDataSize'),
                 accounts: value.accounts,
             };
         },
@@ -6249,6 +6439,7 @@ async function inspectPreparedOperation(wallet, operation, options, context) {
     if (!wallet?.inspectTransaction) {
         throw new Error('Wallet adapter does not support unsigned transaction inspection');
     }
+    resolveTransactionBuildOptions(options, wallet);
     const transaction = operation.plan.transactions[0];
     const description = describePreparedOperation(operation);
     const inspection = context
@@ -6943,13 +7134,17 @@ let Arete$1 = class Arete {
                 cause,
             });
         }
+        const sendOptions = {
+            ...(options?.send ?? {}),
+        };
+        if (options?.signers !== undefined) {
+            sendOptions.signers = options.signers;
+        }
+        // Version/resource options are validated before anything reaches the
+        // adapter, so an unsupported request throws the typed options error rather
+        // than a wrapped execution failure.
+        resolveTransactionBuildOptions(sendOptions, wallet);
         try {
-            const sendOptions = {
-                ...(options?.send ?? {}),
-            };
-            if (options?.signers !== undefined) {
-                sendOptions.signers = options.signers;
-            }
             const result = await wallet.signAndSend(instructions, sendOptions, {
                 transactionTransport: options?.transactionTransport ?? this._transactions,
             });
@@ -6963,9 +7158,7 @@ let Arete$1 = class Arete {
         const defaults = this.executionDefaults;
         return executePreparedOperation(this, prepared, {
             wallet: options?.wallet ?? defaults?.wallet,
-            send: defaults?.send || options?.send
-                ? { ...(defaults?.send ?? {}), ...(options?.send ?? {}) }
-                : undefined,
+            send: mergeSendOptions(defaults?.send, options?.send),
             signers: options?.signers ?? defaults?.signers,
             transactionTransport: options?.transactionTransport ?? defaults?.transactionTransport,
             signerRegistry: options?.signerRegistry ?? defaults?.signerRegistry,
@@ -7279,9 +7472,7 @@ async function createSession(definition, ...args) {
             return executionHost.transaction(instructions, {
                 wallet: transactionOptions?.wallet ?? defaults?.wallet,
                 transactionTransport: transactionOptions?.transactionTransport ?? transactions,
-                send: defaults?.send || transactionOptions?.send
-                    ? { ...(defaults?.send ?? {}), ...(transactionOptions?.send ?? {}) }
-                    : undefined,
+                send: mergeSendOptions(defaults?.send, transactionOptions?.send),
                 errors: transactionOptions?.errors,
                 signers: signers.length > 0 ? signers : undefined,
             });
@@ -7292,9 +7483,7 @@ async function createSession(definition, ...args) {
             return executionHost.execute(prepared, {
                 wallet: executionOptions?.wallet ?? defaults?.wallet,
                 transactionTransport: executionOptions?.transactionTransport ?? defaults?.transactionTransport ?? transactions,
-                send: defaults?.send || executionOptions?.send
-                    ? { ...(defaults?.send ?? {}), ...(executionOptions?.send ?? {}) }
-                    : undefined,
+                send: mergeSendOptions(defaults?.send, executionOptions?.send),
                 signers: configuredSigners,
                 signerRegistry,
                 availableSignerAddresses: executionOptions?.availableSignerAddresses ?? defaults?.availableSignerAddresses,
@@ -7517,7 +7706,9 @@ exports.STACK_RUNTIME_EXTENSIONS = STACK_RUNTIME_EXTENSIONS;
 exports.SYSTEM_PROGRAM_ADDRESS = SYSTEM_PROGRAM_ADDRESS;
 exports.SubscriptionRegistry = SubscriptionRegistry;
 exports.TOKEN_2022_PROGRAM_ADDRESS = TOKEN_2022_PROGRAM_ADDRESS;
+exports.TRANSACTION_RESOURCE_OPTION_KEYS = TRANSACTION_RESOURCE_OPTION_KEYS;
 exports.TransactionExecutionError = TransactionExecutionError;
+exports.TransactionOptionsError = TransactionOptionsError;
 exports.TransactionTransportError = TransactionTransportError;
 exports.account = account;
 exports.appendFlowTransactions = appendFlowTransactions;
@@ -7601,6 +7792,7 @@ exports.resolveAmount = resolveAmount;
 exports.resolveAmountToRaw = resolveAmountToRaw;
 exports.resolveAmountsToRaw = resolveAmountsToRaw;
 exports.resolveTokenProgramAddress = resolveTokenProgramAddress;
+exports.resolveTransactionBuildOptions = resolveTransactionBuildOptions;
 exports.safeToRawAmount = safeToRawAmount;
 exports.serializeInstructionData = serializeInstructionData;
 exports.serializeViewKey = serializeViewKey;
@@ -7608,6 +7800,7 @@ exports.stackQuery = stackQuery;
 exports.stringifyBigints = stringifyBigints;
 exports.toJsonValue = toJsonValue;
 exports.toRawAmount = toRawAmount;
+exports.toWireResourceOptions = toWireResourceOptions;
 exports.transactionOperation = transactionOperation;
 exports.unwrapOperationExecutionError = unwrapOperationExecutionError;
 exports.validateAccountResolution = validateAccountResolution;