Custom Records 自定義 TLV 記錄

Onion Payload TLV Type Allocation:

Type Ranges:

0 - 63,999: Protocol-defined (reserved by BOLT spec)

Common Protocol Types:
  • 2: amt_to_forward (forward amount)
  • 4: outgoing_cltv_value (outbound CLTV)
  • 6: short_channel_id (next hop channel)
  • 8: payment_data (payment_secret + total_msat)
  • 10: encrypted_recipient_data (blinded paths)
  • 16: payment_metadata

64,000+: Custom records (application use)
  • Must be odd (odd type = optional)
  • Receiver can safely ignore if unrecognized

Odd/Even Rule ("it's ok to be odd"):

Even types: Must understand, otherwise fail
Odd types: Optional, can ignore if not understood

Custom Records should use odd types:
  65537, 65539, 65541, ...

This ensures backward compatibility:
  Old nodes can ignore unrecognized custom records

Custom Records Use Cases:

1. Keysend (Spontaneous Payments):

Type 5482373484 (0x1466a3ac): keysend preimage

Payer generates preimage, sends in custom record
Receiver extracts preimage to complete payment

{
  5482373484: <32-byte preimage>
}

2. Messaging:

Whatsat / Sphinx Chat style:

Type 34349334: Text message
Type 34349337: Sender info
Type 34349339: Timestamp

{
  34349334: "Hello, Lightning!",
  34349337: <sender_pubkey>,
  34349339: 1699999999
}

3. Application Identification:

Identifying payment source application:

Type 65535: Application identifier

{
  65535: "my-app-v1.0"
}

Receiver can apply special handling based on this info

4. Order Information:

E-commerce scenario:

{
  65537: "order_id:12345",
  65539: "product:widget",
  65541: "quantity:3"
}

Or using JSON:
{
  65537: '{"order":"12345","product":"widget","qty":3}'
}

Sending and Receiving Custom Records:

LND Sending (using lncli):

# Keysend with custom record
lncli sendpayment \
  --dest <pubkey> \
  --amt 1000 \
  --keysend \
  --data 65537=<hex_encoded_data>

# Multiple custom records
lncli sendpayment \
  --dest <pubkey> \
  --amt 1000 \
  --keysend \
  --data 65537=48656c6c6f \
  --data 65539=576f726c64

LND Receiving (subscribe to invoices):

// gRPC subscription
stream := client.SubscribeInvoices(ctx, &lnrpc.InvoiceSubscription{})

for {
    invoice, _ := stream.Recv()
    for _, htlc := range invoice.Htlcs {
        // Read custom records
        for typ, data := range htlc.CustomRecords {
            fmt.Printf("Type %d: %x\n", typ, data)
        }
    }
}

Core Lightning:

# Send
lightning-cli keysend <node_id> <amount> \
  extratlvs='{"65537": "48656c6c6f"}'

# Receive (via hook or listinvoices)
{
  "extra_tlvs": [
    { "type": 65537, "value": "48656c6c6f" }
  ]
}

Community-Used Custom Record Types:

Known Types (unofficial, community consensus):

5482373484 (0x1466a3ac): Keysend preimage
  Used for spontaneous payments without invoices

34349334: Whatsat text message
34349337: Whatsat sender
34349339: Whatsat timestamp
34349343: Whatsat signature

7629169: Podcasting 2.0 boost
7629171: Podcasting 2.0 stream

133773310: Zap (Nostr) sats

Recommendations for Choosing New Types:

1. Use sufficiently large random number (avoid collisions)
2. Use odd number (ensure optional)
3. Document your type usage
4. Consider registering with community

Example generation:
import random
type_id = 65536 + random.randint(0, 2**32) | 1  # ensure odd

Custom Records Limitations:

Size Limits:

Onion payload total size is limited:
  • Max ~1300 bytes per hop payload
  • Need to subtract space for protocol fields
  • Custom records available space ~1000 bytes

Recommendations:
  • Keep data concise
  • Use hash references for large data
  • Consider compression

Privacy Considerations:

Custom records only visible to final recipient:
  • Intermediate nodes cannot read (onion encrypted)
  • But receiver can see all content
  • Don't send sensitive info to untrusted receivers

Note:
  • Data is not encrypted, only onion wrapped
  • Receiver can store and share
  • Consider additional encryption for sensitive data

Compatibility:

Not all nodes support custom records:
  • Old versions may ignore
  • Some implementations may have bugs
  • Test target receiver's support

LND: Full support
Core Lightning: Supported (may need config)
Eclair: Partial support