DamageBDD Lightning Swap Funding Steps

Documented swap-funding step interfaces, with explicit validation, invoice and contractor-payment boundaries.

Updated 2026-10-11Read as Markdown ↗

Overview

This reference retains the documented steps_swap_funding.erl phrases and variables. Confirm them against the installed release before running a feature. It is not evidence of a complete live payment service.

The described integration coordinates a Lightning hold invoice, a swap option and a job-registry entry. Its intended lifecycle is request, pending payment, settlement or cancellation, job acceptance and any separately authorised payout. Top-ups use a different path; see payment flows.

A disappearing in-memory entry or a completed job flag is not sufficient payment evidence. Verify settlement with the payment backend and confirm any contract/token transfer. Exercise expiry, duplicate events and restart recovery. Contractor compensation remains subject to the work item's terms and the contractor process.

Required Variables

Before using the swap steps, define the following variables in your feature:

Variable	Meaning
swap_channel_id	State channel ID used for the JobRegistry entry
funder_ae_account	AE account that will receive DAMAGE rewards
lock_sats	Satoshis the funder pays to fund the issue
payout_damage	DAMAGE rewarded to the funder
expiry_seconds	Duration before the option expires

Example:

Given I set the variable "swap_channel_id" to "ch_abc123"
And I set the variable "funder_ae_account" to "ak_fundertest123"
And I set the variable "lock_sats" to "20000"
And I set the variable "payout_damage" to "500"
And I set the variable "expiry_seconds" to "86400"

Step Reference

These are the step phrases described by the existing integration guide. Their runtime availability and implementation must be checked in the release.

When I fund the tracked issue with a Lightning swap option

Creates:

A Lightning hold invoice
A LightningSwapOption entry on-chain
A JobRegistry record inside the state channel

Usage:

When I fund the tracked issue with a Lightning swap option

Prerequisites:

Given I use GitHub repo "damagebdd/damagebdd"
And I track issue "#42"

Effect on context:

swap_option_id
swap_invoice
swap_payment_hash
job_id
job_channel_pid

Then the Lightning swap option should be open for the tracked issue

Asserts that the JobRegistry job exists and is in open state.

Then the Lightning swap option should be open for the tracked issue

Then the Lightning invoice should be paid

Checks whether the Lightning invoice has been settled.

The earlier integration guide used these indicators:

damage_swap_option no longer tracks the payment hash,
the swap option has been exercised on-chain.

Then the Lightning invoice should be paid

Then the funder should receive DAMAGE rewards

The intended assertion checks whether the funder account received the quoted DAMAGE amount:

Then the funder should receive DAMAGE rewards

The balance check uses damage_ae:balance/1.

Then the contractor should be paid for the tracked issue

The intended assertion concerns a completed job and payout. Confirm the actual payment receipt and recipient; a completed flag alone is insufficient.

Then the contractor should be paid for the tracked issue

Full Example Feature

The following is an illustrative integration feature using placeholder accounts. It has not been executed for this documentation revision; confirm the step implementations and use a controlled test environment.

Feature: Fund contractor work via Lightning swaps

  Background:
    Given I use GitHub repo "damagebdd/damagebdd"
    And I track issue "#42"

    And I set the variable "swap_channel_id" to "ch_abcd123"
    And I set the variable "funder_ae_account" to "ak_fundertest123"
    And I set the variable "lock_sats" to "20000"
    And I set the variable "payout_damage" to "500"
    And I set the variable "expiry_seconds" to "86400"

  Scenario: Funder pays the invoice and receives DAMAGE
    When I fund the tracked issue with a Lightning swap option
    Then the Lightning swap option should be open for the tracked issue

    # User pays the invoice externally
    Then the Lightning invoice should be paid

    And the funder should receive DAMAGE rewards
    And the contractor should be paid for the tracked issue

Validation required for an offered service

Record the invoice and contract state transitions, recipient amounts, expiry, cancellation and recovery behaviour. Link those results to the execution and acceptance records. Do not infer trustless settlement or guaranteed payment from this feature text. See the swap FAQ.