Skip to content

lnrpc: clarify payment request expiry semantics #11058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ziggie1984 merged 1 commit into from
Aug 18, 2026
+116 −31
Merged

lnrpc: clarify payment request expiry semantics #11058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 46 additions & 17 deletions lnrpc/lightning.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

42 changes: 42 additions & 0 deletions lnrpc/lightning.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4529,19 +4529,61 @@ message PayReqString {
string pay_req = 1;
}
message PayReq {
// The hex-encoded compressed public key of the payment request signer. For
// non-blinded payment requests, this is the payee's node public key.
string destination = 1;

// The hex-encoded payment hash (BOLT-11 `p` field).
string payment_hash = 2;

// The amount in satoshis. 0 if the payment request does not specify an
// amount. Any millisatoshi remainder is truncated; see `num_msat` for the
// exact value.
int64 num_satoshis = 3;

// The creation time of the payment request as a Unix timestamp (seconds).
int64 timestamp = 4;

// The expiry duration in seconds relative to the `timestamp` field. If
// the payment request omits the BOLT-11 `x` expiry field, the BOLT-11
// default of 3600 seconds is returned.
int64 expiry = 5;

// The description (memo) of the payment (BOLT-11 `d` field). Empty if the
// payment request carries a description hash instead.
string description = 6;

// The hex-encoded SHA-256 hash of the payment description (BOLT-11 `h`
// field). Empty if not present.
string description_hash = 7;

// The on-chain fallback address (BOLT-11 `f` field), encoded for the active
// network. Empty if not present.
string fallback_addr = 8;

@ziggie1984 ziggie1984 Aug 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's maybe add proper description to all of them ?

@Lrifton92 Lrifton92 Aug 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 — since this PR is about making the PayReq semantics explicit, here is a draft for the remaining fields, checked against what DecodePayReq in rpcserver.go actually fills in from zpay32.Invoice (in case it saves @starius a round trip; feel free to reword):

message PayReq {
    // The hex-encoded compressed public key of the payee (the node that
    // created the payment request).
    string destination = 1;

    // The hex-encoded payment hash (BOLT-11 `p` field).
    string payment_hash = 2;

    // The amount in satoshis. 0 if the payment request does not specify
    // an amount. Any millisatoshi remainder is truncated; see num_msat for
    // the exact value.
    int64 num_satoshis = 3;

    // The creation time of the payment request as a Unix timestamp
    // (seconds).
    int64 timestamp = 4;

    // The expiry duration in seconds relative to the `timestamp` field. If
    // the payment request omits the BOLT-11 `x` expiry field, the BOLT-11
    // default of 3600 seconds is returned.
    int64 expiry = 5;

    // The description (memo) of the payment (BOLT-11 `d` field). Empty if
    // the payment request carries a description_hash instead.
    string description = 6;

    // The hex-encoded SHA-256 hash of the payment description (BOLT-11 `h`
    // field). Empty if not present.
    string description_hash = 7;

    // The on-chain fallback address (BOLT-11 `f` field), encoded for the
    // active network. Empty if not present.
    string fallback_addr = 8;

    // The minimum CLTV expiry delta to use for the final hop (BOLT-11 `c`
    // field). If the payment request omits it, lnd's assumed default
    // (zpay32.DefaultAssumedFinalCLTVDelta) is returned.
    int64 cltv_expiry = 9;

    // Route hints that can each be individually used to assist in reaching
    // the invoice's destination (BOLT-11 `r` field).
    repeated RouteHint route_hints = 10;

    // The payment address / payment secret (BOLT-11 `s` field), used for MPP
    // and required by newer invoices. All-zero (32 bytes) if not present.
    // When using REST, this field is base64 encoded.
    bytes payment_addr = 11;

    // The amount in millisatoshis. 0 if the payment request does not
    // specify an amount.
    int64 num_msat = 12;

    // The feature bits advertised in the payment request (BOLT-11 `9`
    // field).
    map<uint32, Feature> features = 13;

    // The blinded payment paths included in the payment request, if any.
    repeated BlindedPaymentPath blinded_paths = 14;
}

Notes on the non-obvious ones, from the implementation:

  • num_satoshis / num_msat: both come from payReq.MilliSat, which is nil for amountless invoices → both are 0; num_satoshis is MilliSat.ToSatoshis() so it truncates sub-sat amounts.
  • payment_addr: payReq.PaymentAddr.UnwrapOr([32]byte{}) → 32 zero bytes when the s field is absent, not an empty slice.
  • description_hash: hex.EncodeToString of an empty slice → "" when absent.
  • cltv_expiry: payReq.MinFinalCLTVExpiry() falls back to DefaultAssumedFinalCLTVDelta; I referenced the constant rather than the number so the comment doesn't rot.

@starius starius Aug 17, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


// The minimum CLTV expiry delta for the final hop (BOLT-11 `c` field). If
// the payment request omits it, `zpay32.DefaultAssumedFinalCLTVDelta` is
// returned. This field is ignored for blinded payment paths.
int64 cltv_expiry = 9;

// Route hints that can each be individually used to assist in reaching the
// payment request's destination (BOLT-11 `r` field).
repeated RouteHint route_hints = 10;

// The payment address, also known as the payment secret (BOLT-11 `s`
// field). This value is used in MPP payments and required by newer payment
// requests. It is 32 zero bytes if not present. When using REST, this field
// is base64 encoded.
bytes payment_addr = 11;

// The amount in millisatoshis. 0 if the payment request does not specify an
// amount.
int64 num_msat = 12;

// The feature bits advertised in the payment request (BOLT-11 `9` field).
map<uint32, Feature> features = 13;

// The blinded payment paths included in the payment request, if any.
repeated BlindedPaymentPath blinded_paths = 14;
}

Expand Down
42 changes: 28 additions & 14 deletions lnrpc/lightning.swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6751,63 +6751,77 @@
"type": "object",
"properties": {
"destination": {
"type": "string"
"type": "string",
"description": "The hex-encoded compressed public key of the payment request signer. For\nnon-blinded payment requests, this is the payee's node public key."
},
"payment_hash": {
"type": "string"
"type": "string",
"description": "The hex-encoded payment hash (BOLT-11 `p` field)."
},
"num_satoshis": {
"type": "string",
"format": "int64"
"format": "int64",
"description": "The amount in satoshis. 0 if the payment request does not specify an\namount. Any millisatoshi remainder is truncated; see `num_msat` for the\nexact value."
},
"timestamp": {
"type": "string",
"format": "int64"
"format": "int64",
"description": "The creation time of the payment request as a Unix timestamp (seconds)."
},
"expiry": {
"type": "string",
"format": "int64"
"format": "int64",
"description": "The expiry duration in seconds relative to the `timestamp` field. If\nthe payment request omits the BOLT-11 `x` expiry field, the BOLT-11\ndefault of 3600 seconds is returned."
},
"description": {
"type": "string"
"type": "string",
"description": "The description (memo) of the payment (BOLT-11 `d` field). Empty if the\npayment request carries a description hash instead."
},
"description_hash": {
"type": "string"
"type": "string",
"description": "The hex-encoded SHA-256 hash of the payment description (BOLT-11 `h`\nfield). Empty if not present."
},
"fallback_addr": {
"type": "string"
"type": "string",
"description": "The on-chain fallback address (BOLT-11 `f` field), encoded for the active\nnetwork. Empty if not present."
},
"cltv_expiry": {
"type": "string",
"format": "int64"
"format": "int64",
"description": "The minimum CLTV expiry delta for the final hop (BOLT-11 `c` field). If\nthe payment request omits it, `zpay32.DefaultAssumedFinalCLTVDelta` is\nreturned. This field is ignored for blinded payment paths."
},
"route_hints": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/lnrpcRouteHint"
}
},
"description": "Route hints that can each be individually used to assist in reaching the\npayment request's destination (BOLT-11 `r` field)."
},
"payment_addr": {
"type": "string",
"format": "byte"
"format": "byte",
"description": "The payment address, also known as the payment secret (BOLT-11 `s`\nfield). This value is used in MPP payments and required by newer payment\nrequests. It is 32 zero bytes if not present. When using REST, this field\nis base64 encoded."
},
"num_msat": {
"type": "string",
"format": "int64"
"format": "int64",
"description": "The amount in millisatoshis. 0 if the payment request does not specify an\namount."
},
"features": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/lnrpcFeature"
}
},
"description": "The feature bits advertised in the payment request (BOLT-11 `9` field)."
},
"blinded_paths": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/lnrpcBlindedPaymentPath"
}
},
"description": "The blinded payment paths included in the payment request, if any."
}
}
},
Expand Down
Loading