stxer 0.6.1 → 0.8.0

package/dist/transaction.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Transaction-building helpers for the simulator.
+ *
+ * The simulator does NOT verify signatures — it derives `tx-sender`
+ * from the `signer` field (= hash160 of the public key) plus the
+ * `hashMode` byte. By overriding those two fields on an *unsigned*
+ * transaction, you can simulate any sender without a private key.
+ *
+ * {@link setSender} performs the override; {@link buildUnsignedContractCallHex}
+ * combines the unsigned-tx builder from `@stacks/transactions` with
+ * `setSender` and returns a hex string ready to drop into a
+ * `{ Transaction: <hex> }` simulation step.
+ */
+import { type StacksNetworkName } from '@stacks/network';
+import { type ClarityValue, PostConditionMode, type StacksTransactionWire } from '@stacks/transactions';
+/**
+ * Override the spending condition's `signer` (and `hashMode`) so the
+ * simulator treats `tx-sender` as `sender`.
+ *
+ * Single-sig and multi-sig flavours are both handled — the multi-sig
+ * spending condition is rebuilt with empty signature fields because
+ * the simulator never validates signatures.
+ */
+export declare function setSender(tx: StacksTransactionWire, sender: string): StacksTransactionWire;
+export interface ContractCallTxArgs {
+    /** Principal to set as `tx-sender`. */
+    sender: string;
+    /** Fully-qualified contract id, e.g. `"SP1G48….dia-oracle"`. */
+    contract: string;
+    functionName: string;
+    functionArgs: ClarityValue[];
+    /** microSTX. Defaults to 1_000. */
+    fee?: number;
+    /** Nonce to declare. Caller is responsible for sequencing. */
+    nonce: number;
+    network?: StacksNetworkName;
+    /**
+     * Post-condition mode. Defaults to `Allow` so the simulator runs
+     * the call regardless of asset movements; switch to `Deny` + an
+     * explicit list when a test wants to assert post-condition
+     * enforcement.
+     */
+    postConditionMode?: PostConditionMode;
+}
+/**
+ * Build an unsigned contract-call transaction with `sender` patched
+ * in via {@link setSender}, then return the serialized hex (no `0x`
+ * prefix). Drop the result directly into `{ Transaction: <hex> }`.
+ *
+ * @example
+ * ```typescript
+ * import { Cl } from '@stacks/transactions';
+ * import { buildUnsignedContractCallHex } from 'stxer';
+ *
+ * const txHex = await buildUnsignedContractCallHex({
+ *   sender: 'SP3573...',
+ *   contract: 'SM3VDXK...sbtc-deposit',
+ *   functionName: 'complete-deposit-wrapper',
+ *   functionArgs: [Cl.bufferFromHex(txid), Cl.uint(0), Cl.uint(amount), ...],
+ *   nonce: 5,
+ * });
+ * await submitSimulationSteps(sim, { steps: [{ Transaction: txHex }] });
+ * ```
+ */
+export declare function buildUnsignedContractCallHex(args: ContractCallTxArgs): Promise<string>;
+/**
+ * Build a `Cl.contractPrincipal` from a `"SP….name"` id string.
+ * Trips on standard principals or malformed ids — those should use
+ * `Cl.principal` directly.
+ */
+export declare function ftPrincipal(contractId: string): ClarityValue;