Remote Signing

NOTE: This page is only relevant if your account has been configured to use remote signing. If you don't know what that is, it's likely this page is not relevant to you. If you think you might need remote signing, please reach out via slack or at support@lightspark.com.

import express from "express";
import {
  AccountTokenAuthProvider,
  LightsparkClient,
  RemoteSigningWebhookHandler,
  WebhookEvent,
  WebhookEventType,
  WEBHOOKS_SIGNATURE_HEADER,
  verifyAndParseWebhook,
  hexToBytes,
} from "@lightsparkdev/lightspark-sdk";
import {
  EnvCredentials,
  getCredentialsFromEnvOrThrow,
} from "@lightsparkdev/lightspark-sdk/env";

const app = express();

app.post("/webhook", (req, res) => {
  const webhookEvent = await verifyAndParseWebhook(
    req.body,
    req.headers[WEBHOOKS_SIGNATURE_HEADER],
    ({}).LIGHTSPARK_WEBHOOK_SIGNING_KEY
  );

  switch (webhookEvent.eventType) {
    case WebhookEventType.REMOTE_SIGNING:
      const credentials = getCredentialsFromEnvOrThrow();
      const lightsparkClient = new LightsparkClient(
        new AccountTokenAuthProvider(
          credentials.apiTokenClientId,
          credentials.apiTokenClientSecret
        ),
        credentials.baseUrl
      );

      const validator = {
        should_sign: (webhook: WebhookEvent) => true,
      };
      const remoteSigningHandler = new RemoteSigningWebhookHandler(
        lightsparkClient,
        hexToBytes(({}).RK_MASTER_SEED_HEX),
        validator
      );

      const result = remoteSigningHandler.handleWebhookRequest(
        req.body,
        req.headers[WEBHOOKS_SIGNATURE_HEADER],
        ({}).RK_WEBHOOK_SECRET
      );
      break;

    default:
      call.respond(HttpStatusCode.OK);
      return "Unhandled webhook event type " + webhookEvent.eventType + ".";
  }
});

data: {
    sub_event_type: "DERIVE_KEY_AND_SIGN",
    bitcoin_network: BitcoinNetwork,
    signing_jobs: SigningJob[],
}

interface SigningJob {
    id: string;
    derivation_path: string;
    message: string;
    add_tweak?: string;
    mul_tweak?: string;
    is_raw: boolean;
    per_commitment_point_idx: bigint;
    script: string;
    transaction: string;
    amount: bigint;
}

mutation SignMessages(
    $signatures: [IdAndSignature!]!
) {
    sign_messages(input: {
    signatures: $signatures
  }) {
    ...SignMessagesOutputFragment
  }
}

mutation DeclineToSignMessages($payload_ids: [ID!]!) {
  decline_to_sign_messages(input: {
    payload_ids: $payload_ids
  }) {
    ...DeclineToSignMessagesOutputFragment
  }
}

data: {
    sub_event_type: "REQUEST_INVOICE_PAYMENT_HASH",
    invoice_id: string,
    bitcoin_network: BitcoinNetwork,
}

mutation SetInvoicePaymentHash(
  $invoice_id: ID!
  $payment_hash: Hash32!
  $preimage_nonce: Hash32!
) {
  set_invoice_payment_hash(input: {
    invoice_id: $invoice_id
    payment_hash: $payment_hash
    preimage_nonce: $preimage_nonce
  }) {
    ...SetInvoicePaymentHashOutputFragment
  }
}

Note: The preimage nonce is returned along with the payment hash - this is needed so that when the preimage is later requested to be released, Lightspark can provide the nonce so you can recompute the preimage.

data: {
    sub_event_type: "RELEASE_PAYMENT_PREIMAGE",
    bitcoin_network: BitcoinNetwork,
    invoice_id: string,
    preimage_nonce: string, // hex-encoded
}

mutation ReleasePaymentPreimage(
  $invoice_id: ID!
  $payment_preimage: Hash32!
) {
  release_payment_preimage(input: {
    invoice_id: $invoice_id
    payment_preimage: $payment_preimage
  }) {
    ...ReleasePaymentPreimageOutputFragment
  }
}

data: {
    sub_event_type: "RELEASE_PER_COMMITMENT_SECRET",
    per_commitment_point_idx: bigint,
    derivation_path: string,
    bitcoin_network: BitcoinNetwork,
    node_id: ID,
}

mutation ReleaseChannelPerCommitmentSecret(
  $channel_id: ID!
  $per_commitment_secret: Hash32!
  $per_commitment_index: Long!
) {
  release_channel_per_commitment_secret(input: {
    channel_id: $channel_id
    per_commitment_secret: $per_commitment_secret
    per_commitment_index: $per_commitment_index
  }) {
    ...ReleaseChannelPerCommitmentSecretOutputFragment
  }
}

data: {
    sub_event_type: "GET_PER_COMMITMENT_POINT",
    per_commitment_point_idx: bigint,
    derivation_path: string,
    bitcoin_network: BitcoinNetwork,
    node_id: ID,
}

mutation UpdateChannelPerCommitmentPoint(
  $channel_id : ID!
  $per_commitment_point : PublicKey!
  $per_commitment_point_index : Long!
) {
  update_channel_per_commitment_point(input: {
    channel_id: $channel_id
    per_commitment_point_index: $per_commitment_point_index
    per_commitment_point: $per_commitment_point
  }) {
    ...UpdateChannelPerCommitmentPointOutputFragment
  }
}

data: {
    sub_event_type: "REVEAL_COUNTERPARTY_PER_COMMITMENT_SECRET",
    bitcoin_network: BitcoinNetwork,
    per_commitment_secret_idx: bigint,
    per_commitment_secret: string,
    node_id: ID,
}