mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-13 11:35:41 +01:00
Code Issues Projects Releases Wiki Activity

Merge 36553d1ea6 into a09564a8b7

Browse source
This commit is contained in:
Antoine Riard 2025-03-10 14:14:09 +03:00 • committed by GitHub
commit b7fc18e02e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 426 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

245
60-staking-credentials-archi.md Normal file
View file

@ -0,0 +1,245 @@
# Staking Credentials
This document specifies the Staking Credentials architecture and requirements for its constituents
protocols used for constructing anonymous credentials mechanisms in the context of Bitcoin financial
contracts and Civkit functionary services.
This draft is version 0.0.1 of the Staking Credentials architecture.
## Introduction
Staking Credentials is an architecture for Bitcoin financial contracts based on anonymous credentials.
Those credentials are not only unlinking their issuance from their consumption, but also allows the
user staking of credentials to downgrade the costs of entering in future Bitcoin financial contracts
or accessing Civkit functionary services. The quality and thresholds of assets can be selected with
granularity by the contract provider to achieve a satisfying level of risks, combining monetary and
reputation strategies.
Staking Credentials approach is the following: the clients presents a basket of scarce assets
(Lightning preimage, stakes certificates) and blinded credentials to the issuance server, the credentials
are authenticated and yeilded back to the client. Once unblinded the credentials can be used to fulfill
a contract or service request towards a service provider server. The credentials are anonymous in
the sense that a given credential cannot be linked to the protocol instance in which that credential
was initially issued.
The Staking Credentials architecture consists of two protocols: credentials issuance and redemption.
The issuance protocol runs between two endpoints referred to as Requester and Issuer and one
function: Credential Authentication. The entity that implements the Credential Authentication,
referred to as the Issuer, is responsible for counter-signing the credentials in response to requests
from Requester. Issuer might accept different base assets in function of their risk strategy, and
the overhead cost they would like to transfer on the Committer for answering a contract or service
request. Requester and Issuer can agree on an Authentication method in function of the cryptographic
properties aimed for.
The redemption protocol runs between two endpoint reffered to as Client and Provider and
one function: Credential Consumption. The entity that implements the Credential Consumption, referred
to as the Client, is responsible to provide an authenticated Credential covering the contract risk
service request risk, as defined by the Provider. A Client can be a Provider, but those entities
can be also dissociated. An Issuer can be a Provider, but those entities can be also dissociated.
A Client can aggregate authenticated Credentials from multiple Requesters.
The credentials issuance and redemption protocols operate in concert as shown in the figure below:
```
___________ ____________
| | 1. Scarce Asset + Blinded Credentials | |
| |------------------------------------------------->| |
| | | |
| Requester | | Issuer |
------| | 2. Authenticated Binded Credentials | |
| | |<-------------------------------------------------| |
| |___________| |____________|
| ^
| |
| 3. Authenticated Unblinded Credentials |
| |
| 5. Credentials Authentication Validation |
| |
| |
_V__________ _____|________
| | 4. Authenticated Unblinded Credentials + Service Request | |
| |------------------------------------------------------------>| |
| | | |
| Client | | Provider |
| | 6. Contract Acceptance OR Contract Reject | |
| |<------------------------------------------------------------| |
|____________| |______________|
```
This documents describes requirements for both issuance and redemption protocols. It also provides
recommendations on how the architecture should be deployed to ensure the economic effectiveness of
assets, the compatibility of incentives, the conservation of the client UX, the privacy and security
and the decentralization of the ecosystem.
## Terminology
The following terms are used throughout this document.
- Client: An entity that pledges a Credential as assets to redeem a Contract or Service Request.
- Requester: An entity that commit a set of scarce assets to redeem an authenticated Credential from an Issuer.
- Issuer: An entity that accept a scarce asset in exchange of authenticating a Credential.
- Provider: An entity that accept a set of Credentials as payment in case of Contract risk or Service providance to the client.
## Architecture
The Staking Credentials architecture consists of four logical entities -- Client, Issuer, Requester, Provider --
that work in concert for credentials issuance and redemption.
## Credentials Issuance
The credentials issuance is an authorization protocol wherein the Requester presents scarce asset and
blinded credentials to the Issuer for authorization. Usually, the rate of scarce assets to credentials
as placed by the Issuer should have been discovered by the Committer in non-defined protocol phase.
There are a number of scarce assets that can serve, including (non-limited):
- proof-of-payment (e.g Lightning preimage or on-chain txid)
- ecash token
- stakes certificates
- "faithful usage" reward
Issuer should consider which base assets to accept in function of the risk-management strategy they adopt. If
they aim for a 0-risk coverage, where all the contract or service execution risk is transferred on the counterparty,
they should pick up the default of on-chain/off-chain payment, where each contract cost unit should be covered by
a satoshi unit.
The credential issuance can be deployed as "native" or "reward".
In the "native" flow, a scarce asset for credential authentication should be exchanged a priori of a redemption phase:
```
___________ ____________
| | 1. Scarce asset + Credentials | |
| |------------------------------------->| |
| | | |
| Committer | | Issuer |
| | 2. Authenticated Credentials | |
| |<-------------------------------------| |
|___________| |____________|
```
In the "reward" context, one type of scarce asset, i.e contract fees are paid by the Client to the Provider,
a posteriori of a successful redemption phase. A quantity of authenticated credentials should be given
from the linked Issuer, back to the Committer:
```
____________
| | ______________
| | | |
| | | |
| Client | 1. Contract or Service fees | |
| |------------------------------------------>| Provider |
| | | |
|____________| | |
|______________|
|
____________ |
_____________ | | |
| | | | |
| | | | |
| | 3. Authenticated | Issuer |<----------
| Requester | Credentials | |
| |<------------------------| | 2. Unauthenticated Credential Callback
| | |____________|
|_____________|
```
During issuance, the credentials should be blinded to ensure future unlinkability during the redemption phase.
Discovery of assets-to-credentials announced by the Issuer and consumed by the Client should be defined in
its own document.
A privacy-preserving communication protocol between Client and Issuer for credentials issuance should
be defined in its own document.
## Redemption
The redemption protocol is an identification protocol wherein the Client presents authenticated credentials
to the Provider to redeem the acceptance of a contract. The credentials should be unblinded before to be
presented to the Provider. The quantity of credentials attached to the contract request should
satisfy the contract liquidity units as enforced by the Contract Provider. Usually, the rate of credentials
to contract/service unit announced by the Provider should have been discovered by the Committer in a non-defined
protocol phase.
The protocol works as in the figure below:
```
1. Authenticated Unblinded Credential
____________ + ______________
| | Contract/Service Request | |
| |---------------------------------------------------------------------->| |
| | | |
| Client | | Provider |
| | 2. Contract/Service Acceptance OR Contract/Service Reject | |
| |<----------------------------------------------------------------------| |
|____________| |______________|
|
| 3. Contract/Service
| Execution
|------------------------>
```
Depending on the contract execution outcome (success or failure), an additional fee can be paid by the Client
to the Provider. This fee should be determined in function of market forces constraining the type of contract/service
executed.
### Redemption Protocol Extensibility
The Staking Credentials and redemption protocol are both intended to be receptive to extensions that expand
the current set of functionalities through new types or modes of Bitcoin financial contracts covered. Among them,
long-term held contracts based on a timelock exceeding the usual requirements of Lightning payments.
Another type of flow is the correction of the opening asymmetries in multi-party Lightning channels funding transactions.
## Deployment Considerations
### Lightning HTLC routing
In this model, a HTLC forwarder (Committer) send an off-chain payment and a list of blinded credentials to a Routing hop (Issuer).
The Routing hop counter-sign the blinded credentials and send them back to the HTLC forwarder (Credentials Authentication phase).
The HTLC forwarder (Client) unblinds the credential, attach a HTLC and send the request for acceptance to the Routing hop (Contract
Provider). If the quantity of credentials attached satisfies the Routing hop, the HTLC is accepted and forward to the next hop
in the payment path.
This model is shown below:
```
_____________ 1. Off-chain payment + Blinded Credentials ____________
| |----------------------------------------------------->| |
| | | |
| HTLC | 2. Counter-signed Blinded Credentials | Routing | 4. HTLC relay
| forwarder |<-----------------------------------------------------| hop |--------------->
| | | |
| | 3. Unblinded Credentials + HTLC forward | |
|_____________|----------------------------------------------------->|____________|
```
## Security Considerations
The major security risk from an Issuer perspective is the double-spend of the credentials by a Client. In
the context of the Staking Credential architecture, a double-spend is the replay of credential for multiple
Contract requests, therefore provoking a plain timevalue loss if contract fees are not paid by the Client for
each Contract request instance.
The Issuer should keep a private database to log every credential covering a Contract request. This private
database should be accessible by the Contract Provider to validate all the credentials presented for a Contract
request.
A major security risk from a Committer perspective is the tampering of the credentials during transport between
the Committer and Issuers hosts. Credentials could be hijacked based on credentials volume traffic monitoring. As
such credentials transport should be authenticated and the packets obfuscate against network-level inspection.
## References
- [Privacy Pass Architecture](https://www.ietf.org/archive/id/draft-ietf-privacypass-architecture-09.html)
- [Mitigating Channel Jamming with Stakes Certificates](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-November/002884.html)
- [Solving channel jamming issue of the lightning network](https://jamming-dev.github.io/book/about.html)
- [Discreet Log Contracts specification](https://github.com/discreetlogcontracts/dlcspecs/)
- [Lightning interactive transaction construction protocol](https://github.com/lightning/bolts/pull/851)
## Copyright
This document is placed in the public domain.

114
61-credentials-issuance.md Normal file
View file

@ -0,0 +1,114 @@
# Credential Issuance
This document specifies the Credentials Issuance protocol inside the Staking Credentials framework.
The messages data format, validation algorithms and implementation considerations are laid out.
This draft is version 0.0.1 of the Credential Issuance protocol.
## Credentials Issuance
The Requester is sending a proof of scarce assets to the Issuer.
The Issuer is sending back an authentication of the scarce assets to the Requester.
+-------+ +-------+
| | | |
| | | |
| |--(1)--- request_credentials_authentication ---->| |
| A | | B |
| | | |
| |<-(2)--- reply_credentials_authentication -------| |
| | | |
| | | |
+-------+ +-------+
### The `request_credentials_authentication` message
This message contains a proof of scarce asset for the credentials and a set of unsigned blinded credentials.
1. type: 37560 (`request_credentials_authentication`)
2. data:
* [`u32`: `session_id`]
* [`point`: `issuance_pubkey`]
* [`assetlen*byte`: `scarce_assets`]
* [`credentiallen*byte`: `blinded_credentials`]
#### Requirements
The sender:
- MUST set `session_id` to a pseudo-randomly generated 4-byte value.
- MUST set `issuance_pubkey` to a public key discovered from a `credential_policy` issued by the receiver.
- MUST NOT send `scarce_assets` if they have not been announced by a previous `credential_policy` issued by this node.
- MUST NOT send `blinded_credentials` of a format which not been previously announced by a `credential_policy` issued by this node.
- MUST set `blinded_credentials` to less than `max_onion_size`.
The receiver:
- if `issuance_pubkey` has not been announced or has been rotated:
MUST reject this authentication request.
- if `scarce_asset` is not supported:
- MUST reject this authentication request.
- if `blinded_credentials` format is not supported:
- MUST reject this authentication request.
- if `blinded_credentials` size is equal or superior to `max_onion_size`:
- MUST reject this authentication request.
- if the `scarce_asset` amount is not covering the quantity of `blinded_credentials` requested for signature as announced by `credential_policy`:
- MUST reject this authentication request.
#### Rationale
The session id purpose is to enable concurrent authentication sessions where multiple set of credentials can be requested for
authentication by the same Requester, and where the order of reception of concurrent request/reply is not guaranteed by the
transport mechanism.
The Issuer should be able to perform independent validation of a scarce asset to counter-sign the blinded credentials, and therefore
apply a risk management policy.
The Issuer should reject unknown blinded credentials as they cannot provide a valid authentication, if they do not support the
underlying cryptosystem.
The onions containing the blinded credentials must be upper bounded in size to be transported over the Lightning onion routing
infrastructure.
The Issuer should enforce the policy ratio between the scarce asset value and the quantity of credentials counter-signed, and
therefore the Issuer risk management policy is respected.
### The `reply_credentials_authentication` message
This message contains an issuance pubkey and a set of signatures for each credential from `request_credentials_authentication`.
1. type: 37561 (`reply_request_credentials_authentication`)
2. data:
* [`u32`: `session_id`]
* [`point`: `issuance_pubkey`]
* [`credentiallen*signature`:`credentials_signature`]
#### Requirements
The sender:
- MUST set `session_id` to the received value in the corresponding `request_credentials_authentication`
- MUST set `credentials_signatures` to less than `max_onion_size`.
- MUST sort the `credentials_signature` in the order of reception of `blinded_credentials` in the corresponding `request_credentials_authentication`
The receiver:
- if `credentials_signature` size is equal or superior to `max_onion_size`:
- MUST reject this authentication reply.
- if the `issuance_pubkey` is not matching the announced key in `credentials_policy`:
- MUST reject this authentication reply.
- MAY add this Issuer identity on a banlist.
- if the signatures are not valid for the `blinded_credentials` sent in the corresponding `request_credentials_authentication`:
- MUST reject this authentication reply.
#### Rationale
The Requester should reject the reply if the issuance pubkey does not match the credential policy one. The issuance key might have
been honestly rotated by the Issuer or the Requester might be under a deanonymization attack.
### Implementations and Deployment Considerations
The credential signature request could constitute a CPU DoS vector, therefore the Issuer should either bound its incoming onions traffic or ensure the minimal proof
of assets scores for an amount high-enough to deter an adversary.
The scarce assets validation performed should be scale up to ensure there is an economic proportion between the forgery cost and the credentials value. E.g, if
on-chain transaction is a supported scarce asset, it should be confirmed with few blocks to avoid a 1-block reorg leading to a "free" dump of authenticated credentials.

67
62-redemption.md Normal file
View file

@ -0,0 +1,67 @@
# Redemption Phase
This document specifies the Redemption protocol inside the Staking Credentials framework.
The messages data format, validation algorithms and implementation considerations are laid out.
This draft is version 0.0.1 of the Redemption phase protocol.
## Credentials Redemption
The Client is sending unblinded credenrtials and a service specific request.
```
+-------+ +-------+
| | | |
| | | |
| |--(1)--- redeem_credentials ------------------>| |
| A | | B |
| | | |
| | | |
| |-------- service_request (non-specified) ----->| |
| | | |
+-------+ +-------+
```
### The `redeem_credentials` message
This message contains a set of unblinded credentials, a set of corresponding credentials signatures, a set of unsigned blinded credentials for the reward mode and a service identifier.
1. type: 37562 (`redeem_credentials`)
2. data:
* [`point`: `issuance_pubkey`]
* [`credentiallen*byte`: `unblinded_credentials`]
* [`credentiallen*signature`: `credentials_signature`]
* [`credentiallen*byte`: `reward_blinded_credentials`]
* [`32*byte`: `service_identifier`]
* [`u32`: `request_identifier`]
#### Requirements
The sender:
- MUST set the sum of `unblinded_credentials`, `credentials_signature` and `blinded_credentials` to less than `max_onion_size`
- MUST sort the `credentials_signature` in the order of reception of `blinded_credentials` in the corresponding `request_credentials_authentication`
- MUST set `service_identifier` to the service identifier requested for redemption
- MUST set `request_identifier` to the service specific request identifier
The receiver:
- if the signatures are not valid for the `unblinded_credentials``:
- MUST reject this service request.
- if the quantity of credentials does not satisfy the ratio announced by a `service_policy`:
- MAY reject this service request.
#### Rationale
The issuance pubkey present avoids issues with propagation delays or key rotation, where the set of credentials are not valid anymore
for the providance of the service.
The 32-byte service identifier should pair with a random unique identifier provided in the `service_policy` gossip issued by this Provider.
The Provider is free to update its `service_policy` at anytime, therefore altering the economic value of the credentials.
### Implementations and Deployment Considerations
An authenticated and encrypted communication channel should be maintained between the Issuer and the Provider to avoid man-in-the-middle, if
the credential Issuance is delegated. Otherwise, credential validation can be forged and the service can be DoSed.