DamageBDD Lightning Swap Funding Steps

Fund GitHub Issues with Lightning → Receive DAMAGE → Pay Contractors Automatically

1. Overview

These DamageBDD steps allow DAMAGE token holders (funders) to finance development work on GitHub issues using Lightning payments. When the funder pays a Lightning invoice:

A Lightning Swap Option is created on-chain.
A JobRegistry entry is opened inside a Damage state channel.
The funder receives DAMAGE tokens as reward.
The contractor receives payment automatically once BDD tests pass.

All behaviour is verifiable, reproducible, and cryptographically linked.

2. How it Works

The lifecycle of a funded issue:

A GitHub issue defines the requested work.
A funder opens a Lightning Swap Option for that issue.
DamageBDD creates:
- a Lightning hold invoice,
- a swap option on-chain,
- an off-chain job in JobRegistry.
The funder pays the Lightning invoice.
The option is exercised automatically, transferring DAMAGE to the funder.
Once BDD tests pass, the contractor is paid (BTC or DAMAGE).
All steps are captured in verifiable BDD scenarios.

3. 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"

4. Step Reference

This section documents all steps provided by the steps_swap_funding.erl module.

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

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

4.3. Then the Lightning invoice should be paid

Checks whether the Lightning invoice has been settled.

The invoice is considered paid when:

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

Then the Lightning invoice should be paid

4.4. Then the funder should receive DAMAGE rewards

Asserts the funder's AE account received the promised DAMAGE amount:

Then the funder should receive DAMAGE rewards

The balance check uses damage_ae:balance/1.

4.5. Then the contractor should be paid for the tracked issue

Validates that:

the JobRegistry entry transitioned to completed
contractor payout logic executed (BTC or DAMAGE)

Then the contractor should be paid for the tracked issue

5. Full Example Feature

Below is a complete working example linking GitHub → Lightning → DAMAGE → Job completion.

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

6. Conceptual Summary

Funders pay with Lightning and receive verifiable DAMAGE tokens.
Contractors receive payment only when BDD tests pass.
JobRegistry + Swap Options + Lightning create an auditable payment pipeline.
Everything is expressed in human-readable BDD, fully reproducible and trustless.

This integrates the Bitcoin Lightning Network with DamageBDD’s deterministic verification pipeline, enabling a crypto-native, provable funding system for open-source and commercial development work.