Reconciliation, Error Handling, and Testing

• owned_balance: This represents the total amount you currently own, including funds that may not be immediately available (e.g., in-flight outgoing payments, in-flight withdrawals, commit fees). It's a snapshot of what you officially own at this instant.
• available_to_send_balance: This represents the amount you can send on the Lightning network right now. It excludes funds that are temporarily locked (e.g., channel reserves).
• available_to_withdraw_balance: This represents the amount you can withdraw to the Bitcoin network right now. It's usually equal to the owned_balance but doesn't include in-flight operations.

const nodeId = "your_node_id_here"; // Replace with your actual node ID

const query = getLightsparkNodeQuery(nodeId);

const response = await client.executeQuery(query);

if (response && response.balances) {

  console.log(`Owned balance: ${response.balances.ownedBalance.originalValue} ${response.balances.ownedBalance.originalUnit}`);

  console.log(`Available to send: ${response.balances.availableToSendBalance.originalValue} ${response.balances.availableToSendBalance.originalUnit}`);

  console.log(`Available to withdraw: ${response.balances.availableToWithdrawBalance.originalValue} ${response.balances.availableToWithdrawBalance.originalUnit}`);

} else {
  console.log("Unable to fetch balances");
}

const account = await client.getCurrentAccount();

if (account) {
  const startDate = new Date('2024-01-01T00:00:00Z').toISOString();
  const endDate = new Date('2024-03-31T23:59:59Z').toISOString();
  const transactions = await account.getTransactions(
    client,
    100, // Limit to 100 transactions
    undefined, // No cursor for pagination
    undefined, // No specific transaction types filter
    startDate, // Start date of the range
    endDate, // End date of the range
    BitcoinNetwork.MAINNET, // Specify the Bitcoin network
  );
  console.log(`Total transactions: ${transactions.count}`);

  transactions.entities.forEach(transaction => {
    console.log(`Transaction ID: ${transaction.id}`);
    console.log(`Amount: ${transaction.amount.originalValue} ${transaction.amount.originalUnit}`);
    console.log(`Status: ${transaction.status}`);
    console.log('---');
  });
} else {
  console.log("Unable to fetch account");
}

{
  "entities": [
    {
      "id": "Transaction:01234567-89ab-cdef-0123-456789abcdef",
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:35:00Z",
      "status": "SUCCESS",
      "resolved_at": "2024-03-15T10:35:00Z",
      "amount": {
        "original_value": 100000,
        "original_unit": "SATOSHI",
        "preferred_currency_unit": "USD",
        "preferred_currency_value_rounded": 3456,
        "preferred_currency_value_approx": 3456.78
      },
      "transaction_hash": "3a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
      "typename": "IncomingPayment"
    },
    {
      "id": "Transaction:fedcba98-7654-3210-fedc-ba9876543210",
      "created_at": "2024-03-14T15:45:00Z",
      "updated_at": "2024-03-14T15:45:00Z",
      "status": "PENDING",
      "resolved_at": null,
      "amount": {
        "original_value": 50000,
        "original_unit": "SATOSHI",
        "preferred_currency_unit": "USD",
        "preferred_currency_value_rounded": 1728,
        "preferred_currency_value_approx": 1728.39
      },
      "transaction_hash": null,
      "typename": "OutgoingPayment"
    }
  ],
  "count": 2
}

const idempotencyKey = "unique_payment_id_123"
const paymentResult = await client.payInvoice({
  nodeId: "your_node_id",
  encodedInvoice: "lnbc...", // The invoice you're paying
  amountMsats: 1000000, // Amount in millisatoshis
  timeoutSecs: 60,
  maximumFeeMsats: 1000,
  idempotencyKey,
});

1. User-Facing Operations (User in Session)
   • Limit retries to 1-2 attempts
   • Keep retry delays short (e.g. 1 second)
   • Provide immediate feedback to the user
   • If retries fail, clearly communicate the issue and suggest next steps
2. Server-to-Server Operations (User Not in Session)
   • Implement exponential backoff for retries
   • Set a reasonable maximum number of retry attempts (e.g. 5)
   • Log each retry attempt for monitoring

• Set appropriate timeout limits for each operation type
• Log all retry attempts and failures
• For critical operations, create fallback mechanisms or manual review processes

1. Obtain a Chainalysis API key.
2. Provide this API key to Lightspark.

• when screening - receiver node’s pubkey
• when registering the transaction - node pubkey, payment hash, amount and timestamp

• Test funding your node with various amounts
• Verify withdrawal webhooks are received and processed correctly
• Ensure your internal accounting system accurately reflects all funding and withdrawal transactions

• If applicable, test high balance scenario
  • Verify high_balance webhook is received
  • Verify your system's response to webhook is as expected
• If applicable, test low balance scenario
  • Verify low_balance webhook is received
  • Verify your system's response to webhook is as expected

• Send small amount payment (e.g., 1000 sats)
  • Verify your system's controls for initiating small payments
  • Ensure outgoing payment webhook is received and user's account is debited
• Send large amount payment (e.g., 1,000,000 sats)
  • Verify your system's controls for initiating large payments
  • Ensure outgoing payment webhook is received and user's account is debited
• Receive small amount payment (e.g., 1000 sats)
  • Verify your system's controls for receiving small payments
  • Ensure incoming payment webhook is received and user's account is credited
• Receive large amount payment (e.g., 1,000,000 sats)
  • Verify your system's controls for receiving large payments
  • Ensure incoming payment webhook is received and user's account is credited

• Simulate 'no route' error and verify handling
• Simulate 'insufficient balance' error and verify handling
• Attempt to send more than available balance
• Send payment with invalid/expired invoice