Spilman Channel

You’re viewing an old version of the Arkade contracts documentation. Go to Your first contract for the current version.

In a Spilman channel, Alice locks funds once and pays Bob in many small steps. Each step is a fully signed transaction that pays Bob more than the one before. Nothing reaches the operator until Bob closes the channel with the latest step. The code uses arkProvider, indexerProvider, serverPubkey, exitTimelock, serverUnrollScript, and hex from Set Up Your Project.

Path	Signatures	Use
Update	Alice, Bob, operator	Bob closes with the latest state
Refund	Alice, operator, after `refundAt`	Bob never closes
Exit update	Alice, Bob, after the exit delay	The operator is unavailable
Exit refund	Alice, after twice the exit delay	The operator is unavailable and Bob never closes

Bob must close before refundAt. After that time, Alice can take back the whole channel through the refund path.

Build the channel

import {
  MnemonicIdentity,
  MultisigTapscript,
  CLTVMultisigTapscript,
  VtxoScript,
  networks,
} from '@arkade-os/sdk';

const alice = MnemonicIdentity.fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about', { isMainnet: false });
const bob = MnemonicIdentity.fromMnemonic('zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong', { isMainnet: false });
const alicePubkey = await alice.xOnlyPublicKey();
const bobPubkey = await bob.xOnlyPublicKey();

// Store refundAt with the contract: another value gives another address
const refundAt = BigInt(Math.floor(Date.now() / 1000)) + 7n * 86400n;

const updateLeaf = MultisigTapscript.encode({
  pubkeys: [alicePubkey, bobPubkey, serverPubkey],
}).script;
const refundLeaf = CLTVMultisigTapscript.encode({
  pubkeys: [alicePubkey, serverPubkey],
  absoluteTimelock: refundAt,
}).script;
const exitUpdateLeaf = CSVMultisigTapscript.encode({
  pubkeys: [alicePubkey, bobPubkey],
  timelock: exitTimelock,
}).script;
const exitRefundLeaf = CSVMultisigTapscript.encode({
  pubkeys: [alicePubkey],
  timelock: { ...exitTimelock, value: exitTimelock.value * 2n },
}).script;

const channel = new VtxoScript([updateLeaf, refundLeaf, exitUpdateLeaf, exitRefundLeaf]);
console.log('Channel address:', channel.address(networks.mutinynet.hrp, serverPubkey).encode());

Alice opens the channel by sending its capacity to this address.

Pay Bob

Each payment builds a transaction that splits the channel between Bob and Alice. Alice signs the transaction and its checkpoint, then sends both to Bob. Bob countersigns and keeps only the latest state. Alice never gets Bob’s signature, so she cannot submit an older state that pays Bob less.

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

const { vtxos } = await indexerProvider.getVtxos({
  scripts: [hex.encode(channel.pkScript)],
  spendableOnly: true,
});
if (vtxos.length === 0) throw new Error('Alice must fund the channel address first');
const channelInput = {
  ...vtxos[0],
  tapLeafScript: channel.findLeaf(hex.encode(updateLeaf)),
  tapTree: channel.encode(),
};
const capacity = BigInt(channelInput.value);

const aliceScript = ArkAddress.decode('tark1...').pkScript; // Alice's Arkade address
const bobScript = ArkAddress.decode('tark1...').pkScript; // Bob's Arkade address

const signAll = (identity: MnemonicIdentity, txs: Transaction[]) =>
  Promise.all(txs.map((tx) => identity.sign(tx)));

// Alice pays Bob `toBob` in total
async function payBob(toBob: bigint) {
  const { arkTx, checkpoints } = buildOffchainTx(
    [channelInput],
    [
      { amount: toBob, script: bobScript },
      { amount: capacity - toBob, script: aliceScript },
    ],
    serverUnrollScript,
  );
  const [aliceArkTx, ...aliceCheckpoints] = await signAll(alice, [arkTx, ...checkpoints]);
  // Bob checks the amounts before he countersigns
  const [bobArkTx, ...bobCheckpoints] = await signAll(bob, [aliceArkTx, ...aliceCheckpoints]);
  return { arkTx: bobArkTx, checkpoints: bobCheckpoints };
}

await payBob(1_000n);
const latest = await payBob(1_500n);

Close the channel

Bob submits the latest state. The operator returns the checkpoint with its signature, and Bob adds the signatures he already holds.

import { combineTapscriptSigs } from '@arkade-os/sdk';
import { base64 } from '@scure/base';

const { arkTxid, signedCheckpointTxs } = await arkProvider.submitTx(
  base64.encode(latest.arkTx.toPSBT()),
  latest.checkpoints.map((c) => base64.encode(c.toPSBT())),
);

const finalCheckpoints = signedCheckpointTxs.map((signed) => {
  const checkpoint = Transaction.fromPSBT(base64.decode(signed));
  const ours = latest.checkpoints.find((c) => c.id === checkpoint.id);
  if (!ours) throw new Error('The operator returned an unknown checkpoint');
  combineTapscriptSigs(ours, checkpoint);
  return base64.encode(checkpoint.toPSBT());
});

await arkProvider.finalizeTx(arkTxid, finalCheckpoints);
console.log('Channel closed:', arkTxid);

Overview

Working with Tapscript

Experimental

Build the channel

Pay Bob

Close the channel

​Build the channel

​Pay Bob

​Close the channel

Build the channel

Pay Bob

Close the channel