Deep dive

Transaction outputs and script paths

Arkade transactions are Bitcoin transactions that consume and create outputs with special Taproot spending paths. They have two key features differentiating them from conventional Bitcoin transactions:

Cooperative execution - The operator verifies and co-signs eligible paths.
Extended programmability - Spending paths can utilize custom opcodes that enable features such as transaction introspection and advanced arithmetic.
Immediate spending - Resulting outputs can fund subsequent Arkade transactions without onchain block confirmation.

Learn more about Arkade outputs, batch outputs, and transaction paths

Script compatibility and path rules

Arkade applies Bitcoin Script semantics to output spending paths during cooperative execution. Published Bitcoin paths remain subject to Bitcoin consensus. There are two types of spending paths:

Collaborative paths (offchain, instant) must include the server pubkey so the operator can co-sign.
Unilateral paths (onchain, timelocked) must include a CSV exit delay using or exceeding the value from getInfo(). The operator’s signature is not required.

const operatorInfo = await operator.getInfo();
const operatorPubkey = hex.decode(operatorInfo.signerPubkey).slice(1);
const exitDelay = BigInt(operatorInfo.unilateralExitDelay);

const collaborativePath = MultisigTapscript.encode({
  pubkeys: [userPubkey, operatorPubkey],
}).script;

const unilateralPath = CSVMultisigTapscript.encode({
  pubkeys: [userPubkey],
  timelock: {
    type: 'seconds',
    value: unilateralExitDelay
  },
}).script;

const contract = new VtxoScript([collaborativePath, unilateralPath]);

CSV (relative timelocks) can only be used for unilateral exit paths. For collaborative paths, you MUST use CLTV (absolute timelocks).

Timelocks

Type	Output Path	Unit	Example
CLTV	Collaborative	Seconds (Unix timestamp)	`BigInt(Date.now() / 1000) + 86400n` (1 day from now)
CSV	Unilateral	Seconds (relative)	`unilateralExitDelay` from `getInfo()`

The SDK provides helpers for common patterns:

// N-of-N multisig
MultisigTapscript.encode({ pubkeys: [alicePubkey, bobPubkey, operatorPubkey] });

// Absolute timelock (CLTV)
CLTVMultisigTapscript.encode({
  pubkeys: [userPubkey, operatorPubkey],
  absoluteTimelock: BigInt(Math.floor(Date.now() / 1000)) + 86400n // 1 day from now
});

// Relative timelock (CSV) - unilateral exit path in case of server liveness failure; emergency only
CSVMultisigTapscript.encode({
  pubkeys: [userPubkey, operatorPubkey],
  timelock: {
    value: 86528n, // ~1 day in seconds
    type: "seconds",
  },
});

Input/output structure

Inputs specify which output and spending path:

const input = {
  txid: output.txid,
  vout: output.vout,
  value: output.value,                                      // Must match exactly
  tapLeafScript: contract.findLeaf(hex.encode(leaf)),   // Spending path
  tapTree: contract.encode(),                           // Full tree
};

Outputs specify destinations:

const outputs = [{ amount: 10000n, script: contract.pkScript }];

Two-phase transaction flow

Arkade uses a two-phase protocol for virtual (offchain) transactions:

SubmitTx - Client submits signed transaction + unsigned checkpoints → operator validates, co-signs, and returns partially signed checkpoints
FinalizeTx - Client completes checkpoint signatures → Transaction receives preconfirmation status

const { arkTx, checkpoints } = buildOffchainTx(inputs, outputs, serverUnrollScript);

// Sign the main Arkade transaction
const signedTx = await signer.sign(arkTx);

const { arkTxid, signedCheckpointTxs } = await operator.submitTx(
  base64.encode(signedTx.toPSBT()),
  checkpoints.map((checkpoint) => base64.encode(checkpoint.toPSBT()))
);

// Finalize by fully signing each checkpoint (spending-path signers required)
const finalCheckpoints = await Promise.all(
  signedCheckpointTxs.map(async (signedCheckpoint) => {
    let finalizedCheckpoint = Transaction.fromPSBT(base64.decode(signedCheckpoint));
    finalizedCheckpoint = await signer.sign(finalizedCheckpoint);
    return base64.encode(finalizedCheckpoint.toPSBT());
  })
);

await operator.finalizeTx(arkTxid, finalCheckpoints);

Deep dive into the offchain execution workflow

PSBTs and the Transaction class

You can craft a classic PSBT using @scure/btc-signer. When decoding Arkade PSBTs, pass { allowUnknown: true } to preserve Arkade-specific fields:

const decoded = btc.Transaction.fromPSBT(psbt, { allowUnknown: true });

We strongly recommend using the SDK’s Transaction class instead. It matches @scure/btc-signer 1:1, so the same API calls (and { allowUnknown: true }) work:

import { Transaction } from '@arkade-os/sdk';

const tx = new Transaction();
tx.addInput({
  txid,
  index: vout,
  witnessUtxo: { script: inputScript, amount: inputValue },
});
tx.addOutput({ script: recipientScript, amount: outputValue });

const psbt = tx.toPSBT();
const decoded = Transaction.fromPSBT(psbt);

Next steps

Lightning

Integrate Lightning payments via Arkade intents

Spilman channels

Build payment channels

Experimental contracts

Advanced contract patterns

API reference

Full SDK documentation

Working with Tapscript

Use Cases

Experimental

Transaction outputs and script paths

Script compatibility and path rules

Timelocks

Input/output structure

Two-phase transaction flow

PSBTs and the Transaction class

Next steps

Lightning

Spilman channels

Experimental contracts

API reference

​Transaction outputs and script paths

​Script compatibility and path rules

​Timelocks

​Input/output structure

​Two-phase transaction flow

​PSBTs and the Transaction class

​Next steps

Lightning

Spilman channels

Experimental contracts

API reference

Transaction outputs and script paths

Script compatibility and path rules

Timelocks

Input/output structure

Two-phase transaction flow

PSBTs and the Transaction class

Next steps