# DamageBDD Lightning Swap Funding Steps

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

Canonical HTML: <https://damagebdd.com/features/funding_swap.html>



<a id="overview"></a>

## 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](../payments.md).

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](../contractors.md).


<a id="required-variables"></a>

## Required Variables

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

| Variable | Meaning |
| --- | --- |
| swap<sub>channel</sub><sub>id</sub> | State channel ID used for the JobRegistry entry |
| funder<sub>ae</sub><sub>account</sub> | AE account that will receive DAMAGE rewards |
| lock<sub>sats</sub> | Satoshis the funder pays to fund the issue |
| payout<sub>damage</sub> | DAMAGE rewarded to the funder |
| expiry<sub>seconds</sub> | Duration before the option expires |

Example:

```gherkin
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"
```


<a id="step-reference"></a>

## Step Reference

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


<a id="when-i-fund-the-tracked-issue-with-a-lightning-swap-option"></a>

### 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:

```gherkin
When I fund the tracked issue with a Lightning swap option
```

Prerequisites:

```gherkin
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`


<a id="then-the-lightning-swap-option-should-be-open-for-the-tracked-issue"></a>

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

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

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


<a id="then-the-lightning-invoice-should-be-paid"></a>

### 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.

```gherkin
Then the Lightning invoice should be paid
```


<a id="then-the-funder-should-receive-damage-rewards"></a>

### Then the funder should receive DAMAGE rewards

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

```gherkin
Then the funder should receive DAMAGE rewards
```

The balance check uses `damage_ae:balance/1`.


<a id="then-the-contractor-should-be-paid-for-the-tracked-issue"></a>

### 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.

```gherkin
Then the contractor should be paid for the tracked issue
```


<a id="full-example-feature"></a>

## 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.

```gherkin
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
```


<a id="validation-required-for-an-offered-service"></a>

## 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](../articles/swap_funding_faq.md).