@shocknet/clink-sdk

A TypeScript/JavaScript SDK for the CLINK protocol — Nostr-native static Lightning payment offers and debits.

Table of Contents

• Overview
• Features
• Installation
• Usage
  • 1. Encoding/Decoding Offers and Debits
  • 2. Sending a CLINK Offer Request (Lightning Invoice)
  • 3. Sending a CLINK Debit Request
  • 4. Beacon
  • 5. Enroll
• API Reference
  • ClinkSDK
  • Encoding/Decoding
  • Validators
  • Nostr Helpers (re-exported)
  • Types
• Troubleshooting & Language Porting
• Protocol
• License

Overview

@shocknet/clink-sdk provides a simple, robust interface for working with CLINK (noffer1... and ndebit1...) on Nostr. It enables applications and wallets to create, encode, decode, send, and receive CLINK payment requests and authorizations using Nostr relays, with full support for NIP-44 encryption and the CLINK protocol.

• No web server or Onion Messaging required: Unlike LNURL and Bolt12, all communication is over Nostr relays.
• Compatible with Lightning.Pub, ShockWallet, and other CLINK-enabled apps.
• Implements the official CLINK protocol.

Features

• Encode/decode CLINK Static Offers (noffer1...) and Debits (ndebit1...) per the spec.
• Send CLINK offer (21001), debit (21002), manage (21003), and enroll (21004) requests.
• Fetch a node clink-node beacon (kind 30078) for liveness, display, fees, and advertised kinds.
• NIP-44 encrypted payloads for privacy and security.
• TypeScript types for all protocol payloads and responses.
• Simple, high-level API for wallet and service integration.

Installation

npm install @shocknet/clink-sdk
# or
yarn add @shocknet/clink-sdk

⚠️ Important: Do not install nostr-tools yourself. This SDK pins a compatible version; a second copy often causes decrypt failures and missed responses. Import helpers like SimplePool, nip44, and finalizeEvent from @shocknet/clink-sdk. Details: Troubleshooting Guide.

Usage

1. Encoding/Decoding Offers and Debits

import { nofferEncode, ndebitEncode, decodeBech32, OfferPriceType, generateK1 } from '@shocknet/clink-sdk';

// Encode a CLINK Offer
const noffer = nofferEncode({
  pubkey: '<receiver_pubkey_hex>',
  relay: 'wss://relay.example.com',
  offer: 'my_offer_id',
  priceType: OfferPriceType.Fixed,
  price: 1000 // sats
});

// Decode a CLINK Offer
const decoded = decodeBech32(noffer);
console.log(decoded);
// { type: 'noffer', data: { pubkey, relay, offer, priceType, price } }

// Encode a session ndebit — k1 is TLV type 3
const sessionNdebit = ndebitEncode({
  pubkey: '<node_service_pubkey_hex>',
  relay: 'wss://relay.example.com',
  pointer: '<app_user_pointer>',
  k1: generateK1(),
});

2. Sending a CLINK Offer Request (Lightning Invoice)

import { ClinkSDK, NofferData, generateSecretKey, decodeBech32 } from '@shocknet/clink-sdk';

// First, decode the offer string to get the relay and pubkey
const nofferString = 'noffer1qvqsyqjqxuurvwpcxc6rvvrxxsurqep5vfjk2wf4v33nsenrxumnyvesxfnrswfkvycrwdp3x93xydf5xg6rzce4vv6xgdfh8quxgct9x5erxvspremhxue69uhhgetnwskhyetvv9ujumrfva58gmnfdenjuur4vgqzpccxc30wpf78wf2q78wg3vq008fd8ygtl4qy06gstpye3h5unc47xmee6z';
const decoded = decodeBech32(nofferString);
if (decoded.type !== 'noffer') throw new Error('Invalid offer string');

// Create SDK instance with the decoded relay and pubkey
const sdk = new ClinkSDK({
  privateKey: generateSecretKey(), // Uint8Array
  relays: [decoded.data.relay],
  toPubKey: decoded.data.pubkey,
});

const request: NofferData = {
  offer: decoded.data.offer,
  amount_sats: 1000, // sats (optional for variable/spontaneous offers)
  description: 'coffee for bob', // optional, max 100 chars
  expires_in_seconds: 3600, // optional
  payer_data: { name: 'Alice' }, // optional
};

// Optional: Pass a receipt callback to be notified when the invoice is paid
const receiptCallback = (receipt) => {
  console.log("got receipt", receipt); // { res: 'ok' } or { res: 'ok', preimage: '...' }
};
sdk.Noffer(request, receiptCallback).then(response => {
  if ('bolt11' in response) {
    console.log('Invoice:', response.bolt11);
  } else {
    console.error('Error:', response.error);
  }
});

3. Sending a CLINK Debit Request

import {
  ClinkSDK,
  decodeBech32,
  generateSecretKey,
  newNdebitPaymentRequest,
  newNdebitFullAccessRequest,
  newNdebitBudgetRequest,
} from '@shocknet/clink-sdk';

// Session flow: scan ndebit QR, pay with matching k1
const scanned = decodeBech32('ndebit1...');
if (scanned.type === 'ndebit') {
  const sessionSdk = new ClinkSDK({
    privateKey: generateSecretKey(),
    relays: [scanned.data.relay],
    toPubKey: scanned.data.pubkey,
  });
  const sessionPayment = newNdebitPaymentRequest(
    '<BOLT11_invoice_string>',
    5000,
    scanned.data.pointer,
    scanned.data.k1,
  );
  sessionSdk.Ndebit(sessionPayment).then(/* ... */);
}

// Authorization flow: static pointer
const sdk = new ClinkSDK({
  privateKey: generateSecretKey(),
  relays: ['wss://relay.example.com'],
  toPubKey: '<wallet_service_pubkey_hex>',
});

// Request the service to pay an invoice
const simplePaymentRequest = newNdebitPaymentRequest('<BOLT11_invoice_string>', 5000, 'my_pointer_id');
// Optional: session k1 and/or description — newNdebitPaymentRequest(invoice, amount, pointer, k1?, description?)

sdk.Ndebit(simplePaymentRequest).then(response => {
  if (response.res === 'ok') {
    if ('preimage' in response) {
      console.log('Payment preimage:', response.preimage);
    } else {
      console.log('Payment settled internally.');
    }
  } else if (response.res === 'GFY') {
    console.error('Debit error:', response.error);
  }
});

// Request whitelisting for future payment requests
const fullAccessRequest = newNdebitFullAccessRequest('my_pointer_id');

sdk.Ndebit(fullAccessRequest).then(response => {
  if (response.res === 'ok') {
    console.log('Full access approved:');
  } else if (response.res === 'GFY') {
    console.error('Full access request failed:', response.error);
  }
});

// Request a budget
const budgetRequest = newNdebitBudgetRequest({ number: 1, unit: 'week' }, 1000, 'my_pointer_id');

sdk.Ndebit(budgetRequest).then(response => {
  if (response.res === 'ok') {
    console.log('Budget approved:');
  } else if (response.res === 'GFY') {
    console.error('Budget request failed:', response.error);
  }
});

4. Beacon

Optional. Useful for rich display of node persona (name, avatar, fees, kinds). Recommended for the enroll fast-path: mine at enroll_difficulty instead of probing.

import { ClinkSDK, generateSecretKey } from '@shocknet/clink-sdk';

const sdk = ClinkSDK.fromNprofile('nprofile1...', generateSecretKey());
const beacon = await sdk.Nbeacon();
if (!beacon) throw new Error('no beacon');

console.log(beacon.content.name, beacon.content.fees, beacon.content.supported_kinds);
sdk.Stop();

5. Enroll

Enroll binds your signing key to an account and returns that account's noffer / ndebit / nmanage.

import { ClinkSDK, generateSecretKey, decodeBech32 } from '@shocknet/clink-sdk';

const sdk = ClinkSDK.fromNprofile('nprofile1...', generateSecretKey());
const enrolled = await sdk.Nenroll();
if (enrolled.res !== 'ok') throw new Error(enrolled.error);

const noffer = decodeBech32(enrolled.noffer);
if (noffer.type !== 'noffer') throw new Error('expected noffer');
const invoice = await sdk.Noffer({ offer: noffer.data.offer, amount_sats: 21 });

sdk.Stop();

Nenroll() with no args uses a fresh beacon's enroll_difficulty when present, otherwise probes and remine once on GFY 5. Pass { difficulty: 0 } to probe, or { difficulty: 18 } to skip the lookup. Mining is capped at MAX_ENROLL_POW_BITS (24). A beacon or GFY asking for more is ignored (probe / return the GFY); an explicit { difficulty } above the cap throws.

API Reference

ClinkSDK

new ClinkSDK(settings: ClinkSettings, pool?: AbstractSimplePool)
ClinkSDK.fromNprofile(nprofile: string, privateKey: Uint8Array, opts?: { defaultTimeoutSeconds?: number, pool?: AbstractSimplePool })

• settings: { privateKey: Uint8Array, relays: string[], toPubKey: string, defaultTimeoutSeconds?: number }
• fromNprofile: decodes service pubkey + relays from an nprofile.
• pool: Optional custom Nostr pool (defaults to SimplePool from this package’s pinned nostr-tools). If you pass one, build it with SimplePool imported from @shocknet/clink-sdk.

Methods

• Noffer(data: NofferData, onReceipt?: (receipt: NofferReceipt) => void, timeoutSeconds?: number)
  • Sends a kind: 21001 offer request.
  • Returns a Promise<NofferResponse> that resolves with the invoice or an error.
  • The optional onReceipt callback is triggered when the invoice is paid. You must pass the callback as a parameter—simply defining it is not enough.
  • While waiting for that receipt, the SDK re-subscribes so a confirmation the relay still has (e.g. after switching to a wallet) is delivered when the page is listening again. A replayed invoice is ignored; only { res: "ok" } (optional preimage) counts as the receipt.
• Ndebit(data: NdebitData, timeoutSeconds?: number)
  • Sends a kind: 21002 debit request.
  • Returns a Promise<NdebitResponse> that resolves with the payment/budget confirmation or an error.
• Nmanage(data: NmanageRequest, timeoutSeconds?: number)
  • Sends a kind: 21003 management request.
  • Returns a Promise<NmanageResponse> that resolves with the result of the management action.
• Nbeacon(timeoutSeconds?: number)
  • Fetches the latest kind 30078 d=clink-node beacon (liveness, display, fees, advertised kinds).
• Nenroll(opts?: { difficulty?: number }, timeoutSeconds?: number)
  • Sends a kind 21004 Enroll request ({}). Mines NIP-13 when difficulty > 0, up to MAX_ENROLL_POW_BITS (24). If difficulty is omitted, uses a fresh beacon’s enroll_difficulty when present and in range, otherwise probes and remine once on GFY 5.
• Stop()
  • Closes relay connections on the internal pool. Call when finished so the process can exit cleanly.

Encoding/Decoding

• nofferEncode(offer: OfferPointer): string
• ndebitEncode(debit: DebitPointer): string
• nmanageEncode(manage: ManagePointer): string
• decodeBech32(nip19: string): DecodeResult
• generateK1(): string — 32-byte session identifier as lowercase hex (ndebit TLV 3)
• validateK1(k1: unknown): string — throws unless k1 is 64 lowercase hex chars; returns it unchanged
• isNofferReceipt(parsed: unknown): parsed is NofferReceipt — { res: "ok" } with optional 64-char hex preimage

Validators

For validating inbound/outbound CLINK payloads (e.g. server-side request checks). Each throws on invalid input and returns the typed value on success:

• validateNofferData, validateNdebitData, validateK1, validateBudgetFrequency
• validateNmanageRequest and per-action helpers: validateNmanageCreateOffer, validateNmanageUpdateOffer, validateNmanageDeleteOffer, validateNmanageGetOffer, validateNmanageListOffers, validateOfferFields

Debug

• setDebug(enabled: boolean) — when true, logs relay subscribe/publish/response lifecycle to the console (default false)

Nostr helpers (re-exported)

Pinned by this package — import these from @shocknet/clink-sdk, not from a separate nostr-tools install:

| Export | Kind | Use | |--------|------|-----| | SimplePool | value | Default relay pool; use this if you pass a custom pool | | getPublicKey | value | Derive pubkey from secret key | | generateSecretKey | value | Create a new secret key | | nip19 | value | Bech32 encode/decode (npub / nsec / …) | | finalizeEvent | value | Sign an unsigned event | | nip44 | value | Encrypt/decrypt CLINK payloads (encrypt, decrypt, getConversationKey) | | verifyEvent | value | Verify event signatures (e.g. NIP-98) | | AbstractSimplePool | type | Type for a custom pool argument | | UnsignedEvent | type | Event shape before finalizeEvent |

Types

• NofferData: { offer: string, amount_sats?: number, description?: string, expires_in_seconds?: number, zap?: string, payer_data?: Record<string, string> }
• NofferResponse: { bolt11: string } | { code: number, error: string, range?: { min: number, max: number }, latest?: string }
• NofferReceipt: { res: 'ok', preimage?: string } — Lightning receipts include preimage; internal settlement omits it
• NdebitData: { pointer?: string, amount_sats?: number, bolt11?: string, frequency?: BudgetFrequency, k1?: string, description?: string }
• NdebitResponse: { res: 'ok', preimage?: string } | { res: 'GFY', error: string, code: number }
• OfferPointer: { pubkey: string, relay: string, offer: string, priceType: OfferPriceType, price?: number, currency?: string }
• DebitPointer: { pubkey: string, relay: string, pointer?: string, k1?: string }
• OfferPriceType: enum { Fixed = 0, Variable = 1, Spontaneous = 2 }
• BudgetFrequency: { number: number, unit: 'day' | 'week' | 'month' }
• ClinkSettings: { privateKey: Uint8Array, relays: string[], toPubKey: string, defaultTimeoutSeconds?: number }
• NenrollResponse: { res: 'ok', noffer: string, ndebit: string, nmanage: string } | { res: 'GFY', code: number, error: string, required_difficulty?: number }
• ClinkBeacon: { pubkey: string, created_at: number, operator?: string, content: ClinkBeaconContent }
• AbstractSimplePool, UnsignedEvent: see Nostr helpers above

Troubleshooting & Language Porting

• nostr-tools conflicts, timeouts, and NIP-44 / NIP-19 ports: docs/troubleshooting.md
• Interop vectors for language ports: test-vectors/interop.json

Protocol

• CLINK Protocol Overview

License

MIT