From 1df9e6693f3ff9f00bf69c8d529ba24ba7c06450 Mon Sep 17 00:00:00 2001 From: yukang Date: Fri, 24 Oct 2025 08:39:06 +0800 Subject: [PATCH 1/3] Add documentation for 3 implementations --- README.md | 9 ++++++--- contracts/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 contracts/README.md diff --git a/README.md b/README.md index 786a5d0..8bc473b 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # quantum-resistant-lock-script Quantum resistant lock script on CKB, based on [NIST FIPS 205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) standard. 2 implementations exist: -* A C lock script using [SPHINCS+](https://github.com/sphincs/sphincsplus) -* A Rust lock script using [fips205](https://github.com/integritychain/fips205) +* [A C lock script](./contracts/c-sphincs-all-in-one-lock/) using [SPHINCS+](https://github.com/sphincs/sphincsplus) +* [A Rust lock script](./contracts/sphincs-all-in-one-lock/) using [fips205](https://github.com/integritychain/fips205) +* [A hybrid lock script](./contracts/hybrid-sphincs-all-in-one-lock/) with the implementation of SPHINCS+ utilizing the sphincsplus C library and Rust glue code. + +You can find more details about the implementation strategy in [contracts/README.md](./contracts/README.md). ## Build @@ -43,7 +46,7 @@ In general, the `s` variants take longer to generate a signature, but takes less **NOTE**: the following tool shall be considered deprecated, and only kept here for historic reasons. -This tool is to **convert a default Lock(SECP256K1/blake160) to quantum resistant lock script.**. +This tool is to **convert a default Lock(SECP256K1/blake160) to quantum resistant lock script.**. Follow steps below: diff --git a/contracts/README.md b/contracts/README.md new file mode 100644 index 0000000..037c324 --- /dev/null +++ b/contracts/README.md @@ -0,0 +1,49 @@ + +## SPHINCS+ Lock Implementation Strategy + +We evaluated three different technical approaches for implementing the SPHINCS+ lock with the goal of selecting the most secure and stable version for long-term deployment. + +### The Three Implementation Versions + +The following three versions were created to compare trade-offs in cryptographic assurance, performance, and long-term maintenance: + +| Version | Core SPHINCS+ Logic | CKB Glue Code | Key Technology | +| :--- | :--- | :--- | :--- | +| **1. Pure C** | `sphincsplus` C library (NIST reference) | C99 Standard | High cryptographic assurance and stability. | +| **2. Pure Rust** | `fips205` Rust crate | Rust | Fully Rust-native implementation. | +| **3. Hybrid** | `sphincsplus` C library (NIST reference) | Rust | Combines the proven C core with a Rust wrapper. | + +### Compare Metrics + +While performance was not the primary deciding factor, the contracts showed differences in size and computational cost: + +| Metric | Pure C | Pure Rust | Hybrid | +| :--- | :--- | :--- | :--- | +| **Minimised Contract Size** | $\text{206K}$ | $\text{224K}$ | $\text{277K}$ | +| **Cycle Consumption** | Fastest ($\approx 60\%$ of Rust cycles) | Slowest | Similar to Pure C | + +More details on performance can be found in [Performance Doc](../docs/performance.md). + +### Rationale for Version Selection + +The decision to choose a specific version is driven by two critical factors: **Cryptographic Assurance** and **Long-Term Stability**. + +#### 1. Maximum Cryptographic Assurance + +For a quantum-resistant solution like SPHINCS+, the security of the underlying cryptographic primitive is paramount. + +* The **`sphincsplus` C library** used in the Pure C and Hybrid versions is the **reference implementation** submitted to the NIST Post-Quantum Cryptography Standardization process. It is authored and maintained by the original creators of the SPHINCS+ algorithm. +* This high level of scrutiny and maintenance by leading cryptographers provides the greatest assurance that the implementation is robust and free from subtle cryptographic errors. + +#### 2. Long-Term Stability for HODL Use Case + +SPHINCS+ is intended primarily as a **long-term security solution** for users who wish to secure their assets against potential future quantum attacks (e.g., over a $\text{10-20}$ year period). This use case demands a contract that is maximally stable and immutable. + +* We prioritize **foundational stability** over added features or a rapidly changing ecosystem. +* The **Pure C** implementation, leveraging mature, stable toolchains and the proven `sphincsplus` C library, offers the most reliable foundation for a contract intended to remain unchanged for decades. + +### Conclusion + +We would want to deploy the **Pure C Implementation Contract** due to its combination of superior cryptographic assurance (NIST reference implementation) and its stability for long-term, quantum-resistant asset protection. This approach ensures the most trustworthy and enduring lock on the CKB chain. + +While the Pure Rust and Hybrid versions offer interesting trade-offs, user may also consider them for experimental or short-term use cases where rapid iteration or Rust-native tooling is prioritized over the highest assurance and long-term stability. \ No newline at end of file From bdbbf879db0ea972fee84ce256ce1400dd85a7c8 Mon Sep 17 00:00:00 2001 From: Yukang Date: Fri, 24 Oct 2025 09:59:38 +0800 Subject: [PATCH 2/3] Update README.md Co-authored-by: RetricSu --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8bc473b..0cf1c67 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # quantum-resistant-lock-script -Quantum resistant lock script on CKB, based on [NIST FIPS 205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) standard. 2 implementations exist: +Quantum resistant lock script on CKB, based on [NIST FIPS 205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) standard. + +There are 3 implementations: * [A C lock script](./contracts/c-sphincs-all-in-one-lock/) using [SPHINCS+](https://github.com/sphincs/sphincsplus) * [A Rust lock script](./contracts/sphincs-all-in-one-lock/) using [fips205](https://github.com/integritychain/fips205) From 1150b85fa903830807cd5eaad8eaa09c1a00de93 Mon Sep 17 00:00:00 2001 From: yukang Date: Fri, 24 Oct 2025 08:39:06 +0800 Subject: [PATCH 3/3] Add documentation for 3 implementations --- Makefile | 4 +++- README.md | 4 ++-- contracts/README.md | 8 ++++---- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index bffd309..26398c0 100644 --- a/Makefile +++ b/Makefile @@ -50,7 +50,9 @@ build: cargo build -p $$(basename $$crate) $(MODE_ARGS) $(CARGO_ARGS); \ done; \ for contract in $(sort $(wildcard contracts/*)); do \ - $(MAKE) -e -C $$contract build; \ + if [ -d "$$contract" ]; then \ + $(MAKE) -e -C $$contract build; \ + fi; \ done; \ for crate in $(wildcard tools/*); do \ cargo build -p $$(basename $$crate | tr '-' '_') $(MODE_ARGS) $(CARGO_ARGS); \ diff --git a/README.md b/README.md index 0cf1c67..422172f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # quantum-resistant-lock-script -Quantum resistant lock script on CKB, based on [NIST FIPS 205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) standard. +Quantum resistant lock script on CKB, based on [NIST FIPS 205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) standard. -There are 3 implementations: +There are 3 implementations: * [A C lock script](./contracts/c-sphincs-all-in-one-lock/) using [SPHINCS+](https://github.com/sphincs/sphincsplus) * [A Rust lock script](./contracts/sphincs-all-in-one-lock/) using [fips205](https://github.com/integritychain/fips205) * [A hybrid lock script](./contracts/hybrid-sphincs-all-in-one-lock/) with the implementation of SPHINCS+ utilizing the sphincsplus C library and Rust glue code. diff --git a/contracts/README.md b/contracts/README.md index 037c324..0d675fb 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,7 +1,7 @@ ## SPHINCS+ Lock Implementation Strategy -We evaluated three different technical approaches for implementing the SPHINCS+ lock with the goal of selecting the most secure and stable version for long-term deployment. +We have evaluated three different technical approaches for implementing the SPHINCS+ lock with the goal of selecting the most secure and stable version for long-term deployment. ### The Three Implementation Versions @@ -42,8 +42,8 @@ SPHINCS+ is intended primarily as a **long-term security solution** for users wh * We prioritize **foundational stability** over added features or a rapidly changing ecosystem. * The **Pure C** implementation, leveraging mature, stable toolchains and the proven `sphincsplus` C library, offers the most reliable foundation for a contract intended to remain unchanged for decades. -### Conclusion +### Usage Guidance -We would want to deploy the **Pure C Implementation Contract** due to its combination of superior cryptographic assurance (NIST reference implementation) and its stability for long-term, quantum-resistant asset protection. This approach ensures the most trustworthy and enduring lock on the CKB chain. +We will deploy the **Pure C Implementation Contract** due to its combination of superior cryptographic assurance (NIST reference implementation) and its stability for long-term, quantum-resistant asset protection. This approach ensures the most trustworthy and enduring lock on the CKB chain. -While the Pure Rust and Hybrid versions offer interesting trade-offs, user may also consider them for experimental or short-term use cases where rapid iteration or Rust-native tooling is prioritized over the highest assurance and long-term stability. \ No newline at end of file +While the Pure Rust and Hybrid versions offer interesting trade-offs, you should generally consider them for experimental, short-term scenarios or situations where the benefits of native Rust tooling outweigh the need for maximum guarantees and long-term stability. \ No newline at end of file