Executing transactions

ExecutionClient.execute runs an arbitrary pre-signed EVM transaction inside an intent. Use this when TradingClient doesn’t cover what you’re doing: calling your own contract, deploying, or interacting with a non-AMM Flashnet contract.

Sign and submit

import { ExecutionClient } from "@flashnet/sdk";
import { fetchNonce } from "@flashnet/sdk";
import { encodeFunctionData } from "viem";

const execClient = new ExecutionClient(sparkWallet, {
  gatewayUrl,
  rpcUrl,
  chainId,
});
await execClient.authenticate();

const account = await execClient.getEvmAccount();
const { execution } = await execClient.getNetworkInfo();
const nonce = await fetchNonce(rpcUrl, account.address);

const calldata = encodeFunctionData({
  abi: myContractAbi,
  functionName: "doThing",
  args: [42n],
});

const signedTx = await account.signTransaction({
  chainId: execution.chainId,
  nonce,
  to: myContractAddress,
  value: 0n,
  data: calldata,
  gas: 500_000n,
  maxFeePerGas: 0n,         // zero-gas, see below
  maxPriorityFeePerGas: 0n,
  type: "eip1559",
});

const result = await execClient.execute({ signedTx });

signedTx is the RLP-encoded EIP-1559 transaction, 0x-prefixed.

Bundle deposits with execution

Pass deposits alongside the signed tx to credit Spark transfers in the same intent that runs the call. Each deposit references an existing Spark transfer by id; the caller is responsible for issuing the Spark-side transfer first (execute does not touch the SparkWallet).

const { spark } = await execClient.getNetworkInfo();
const transfer = await sparkWallet.transfer({
  amountSats: 100_000,
  receiverSparkAddress: spark.depositAddress,
});
const sparkTransferId = transfer.id.replace(/-/g, "");

await execClient.execute({
  deposits: [
    { sparkTransferId, amount: 100_000n, asset: { type: "btc" } },
  ],
  signedTx,
});

The intent stays ACCEPTED until the deposit oracle confirms every transfer id against the Spark operator DB. Deposits land before the EVM transaction runs, so doThing can spend the just-credited balance. For the single-intent round-trip (Spark → EVM → Spark) without managing the transfer leg yourself, use TradingClient.swap({ useAvailableBalance: true }).

Zero gas

Flashnet runs baseFeePerGas = 0 and maxPriorityFeePerGas = 0 for every block. There is no base fee to charge and no priority fee to bid. Set both fee fields on your transaction to 0n. Viem’s estimateFeesPerGas defaults will inject non-zero floors that fight you; pass zero explicitly. fetchEip1559Fees(rpcUrl) queries the node and returns the values it currently reports, so a future fee-policy change surfaces here without breaking clients. Note: it ships under the /execution subpath of the SDK barrel, not the root.

import { fetchEip1559Fees } from "@flashnet/sdk/execution";

const fees = await fetchEip1559Fees(rpcUrl);
// { maxFeePerGas: 0n, maxPriorityFeePerGas: 0n } on Flashnet today

Native value (the value field on a transaction) is denominated in 18-decimal wei. One sat is 10_000_000_000 wei (WEI_PER_SAT). Setting value: 100_000n sends 100,000 wei (a tiny fraction of a sat), not 100,000 sats. Multiply by WEI_PER_SAT when you mean sats.

Decoding reverts

When an execute intent’s transaction reverts, the gateway sets status to EXPIRED and packs the revert output into statusMessage:

payload_flagged:stage=Execute outcome=Reverted intent_index=0 \
  tx_hash=0x... reason=reverted:gas_used=189179 output=0x1f2a2005

decodeRevertReason translates the selector back to a name:

import { decodeRevertReason } from "@flashnet/sdk";

const decoded = decodeRevertReason(intent.statusMessage);
console.log(decoded?.name); // "ZeroAmount()"

The default lookup table covers SparkGateway and Conductor errors plus Solidity built-ins. For your own contracts, pass extraErrors:

const decoded = decodeRevertReason(intent.statusMessage, {
  extraErrors: { "0xabcd1234": "MyContractError(uint256)" },
});

For a richer view, traceInnermostRevert walks the call trace and returns the deepest revert frame:

import { traceInnermostRevert } from "@flashnet/sdk/execution";

const frame = await traceInnermostRevert(directRpcUrl, txHash);
if (frame) {
  console.log(frame.address, frame.output, frame.revertReason);
}

The frame returns address, output (ABI-encoded revert bytes), depth, and optionally error and revertReason. There is no input field. traceInnermostRevert uses debug_traceTransaction, which the gateway’s RPC proxy explicitly blocks. Point directRpcUrl at a full-node RPC that exposes the debug namespace (the localnet sequencer does; production typically uses an internal node). Calling against the gateway URL returns null.

Status lifecycle

ACCEPTED -> INCLUDED_PENDING_FINALITY -> FINALIZED
        \-> EXPIRED

Stage	What happened
`ACCEPTED`	Gateway took the intent: signature, expiry, and replay checks passed, and it is queued for sequencer admission. A deposit-shaped intent stays here while the deposit oracle confirms every referenced transfer against the Spark operator DB.
`INCLUDED_PENDING_FINALITY`	The sequencer included the intent in a block. The EVM transaction ran successfully. Validators are signing the finality certificate.
`FINALIZED`	Validators reached quorum. The action ran and settlement dispatched.
`EXPIRED`	Terminal failure. The `expiresAt` deadline passed, gateway admission failed, the deposit oracle could not verify a transfer, or the EVM transaction reverted. `statusMessage` carries the reason.

A reverted transaction does not roll back deposits. The Spark transfers funding the intent are still credited to the EVM address; they just don’t get consumed by the call. Sweep them back to Spark with withdraw or withdrawToken if needed.

When to use this vs TradingClient

Use `TradingClient`	Use `execute`
Trading on Flashnet pools	Calling your own contract
Deposit + swap + withdraw atomically	Deposit + arbitrary call
Permit2 / EIP-2612 plumbing	Custom interaction patterns

The two compose. Most apps run TradingClient for trading and execute for everything else.

Get started

Integrate Flashnet markets

Build on Execution

Reference

Executing transactions

Sign and submit

Bundle deposits with execution

Zero gas

Decoding reverts

Status lifecycle

When to use this vs TradingClient

​Sign and submit

​Bundle deposits with execution

​Zero gas

​Decoding reverts

​Status lifecycle

​When to use this vs TradingClient

Sign and submit

Bundle deposits with execution

Zero gas

Decoding reverts

Status lifecycle

When to use this vs TradingClient