Initial commit

Author: joshdoman

.github/workflows/ci.yaml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  RUSTFLAGS: --deny warnings
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Clippy (default features)
+        run: cargo clippy --all-targets
+
+      - name: Clippy (all features)
+        run: cargo clippy --all-targets --all-features
+
+      - name: Format
+        run: cargo fmt --all -- --check
+
+  test:
+    name: Test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Test default features
+        run: cargo test
+
+      - name: Test all features
+        run: cargo test --all-features

.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "confidential-script-lib"
+version = "0.1.0"
+description = "Authorize on-chain transactions with off-chain verification of Bitcoin script"
+keywords = [ "bitcoin", "script", "kernel", "emulation", "tee" ]
+authors = ["Joshua Doman <joshsdoman@gmail.com>"]
+license = "CC0-1.0"
+homepage = "https://github.com/joshdoman/confidential-script-lib"
+repository = "https://github.com/joshdoman/confidential-script-lib"
+edition = "2024"
+readme = "README.md"
+rust-version = "1.85.0"
+
+[features]
+default = ["std"]
+std = ["bitcoin/std"]
+bitcoinkernel = ["dep:bitcoinkernel"]
+compiler = []
+trace = []
+
+[dependencies]
+bitcoin = "0.32.5"
+bitcoin-units = "0.1.2"
+bitcoinkernel = { version = "0.0.22", optional = true }
+hmac = "0.12.1"
+num-bigint = "0.4.6"
+sha2 = "0.10.9"
+
+[dev-dependencies]
+bitcoinkernel = "0.0.22"

LICENSE.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

README.md

@@ -0,0 +1,154 @@
+# confidential-script-lib
+
+`confidential-script-lib` is a Rust library for emulating Bitcoin script within a Trusted Execution Environment (TEE), such as an AWS Nitro Enclave. It enables the off-chain execution of complex script, by validating unlocking conditions inside a secure environment and then authorizing the transaction using a deterministically derived private key.
+
+This approach allows for confidential execution of complex script, including opcodes not yet supported by the Bitcoin protocol. The actual on-chain footprint is a minimal key-path spend, preserving privacy and efficiency.
+
+## Overview
+
+The library operates on a two-step process: emulation and signing.
+
+1.  **Emulation**: A transaction is constructed using an input spending a *real* `previous_outpoint` with a witness that is a script-path spend from an *emulated* P2TR `script_pubkey`. This library validates this emulated witness using a `Verifier`, which closely matches the API of `rust-bitcoinkernel`. Using the `bitcoinkernel` feature, users can use this default verifier, or they can provide an alternative verifier that enforces a different set of rules (ex: a fork of `bitcoinkernel` that supports Simplicity).
+
+2.  **Signing**: If verified, the library uses the provided parent private key and the merkle root of the *emulated* script path spend to derive a child private key, which corresponds to the internal public key of the *actual* UTXO being spent. The library then updates the transaction with a key-path spend using this child key.
+
+To facilitate offline generation of the real `script_pubkey`, the child key is derived from the parent key using a non-hardened HMAC-SHA512 derivation scheme. This lets users generate addresses using the parent public key, while keeping the parent private key secure.
+
+This library is intended to be run within a TEE, which is securely provisioned with the parent private key. This decouples script execution from on-chain settlemnt, keeping execution private and enabling new functionality with minimal trust assumptions.
+
+## Failsafe Mechanism: Backup Script Path
+
+To prevent funds from being irrecoverably locked if the TEE becomes unavailable, the library allows for the inclusion of an optional `backup_merkle_root` when creating the actual on-chain address. This backup root defines alternative spending paths that are independent of the TEE.
+
+A common use case for this feature is to include a timelocked recovery script (e.g., using `OP_CHECKSEQUENCEVERIFY`). If the primary TEE-based execution path becomes unavailable for any reason, the owner can wait for the timelock to expire and then recover the funds using a pre-defined backup script. This provides a crucial failsafe, ensuring that users retain ultimate control over their assets.
+
+## Extensibility for Proposed Soft Forks
+
+This library can be used to emulate proposed upgrades, such as new opcodes like `OP_CAT` or `OP_CTV` or new scripting languages like Simplicity. It accepts any verifier that adheres to the `rust-bitcoinkernel` API, allowing developers to experiment with new functionality by forking the kernel, without waiting for a soft fork to gain adoption on mainnet.
+
+## Recommended Setup
+
+This library is intended to be used within a Nitro Enclave, integrated with KMS such that any AWS account can provision an identical enclave with the same master private key. For maximum security, the KMS key should be created with a policy making it non-deletable and only accessible to enclaves running a specific image. The policy should also be irrevocable, ensuring the key cannot be used outside the enclave in the future.
+
+To generate the master secret, an enclave should generate a random secret and use `GenerateDataKey` to encrypt it using KMS. To provision a different enclave with the secret, the user should provide the enclave the encrypted data key and the encrypted secret, which the enclave can then decrypt with KMS using `Decrypt`.
+
+Finally, the enclave should be able to expose the master public key, so that users can independently derive the on-chain address they should send funds to.
+
+## Usage
+
+### Verifier
+
+```rust
+/// Trait to abstract the behavior of the bitcoin script verifier, allowing
+/// users to provide their own verifier.
+pub trait Verifier {
+    /// Verify a bitcoin script, mirroring the API of `bitcoinkernel::verify`.
+    ///
+    /// # Arguments
+    /// * `script_pubkey` - The script public key to verify.
+    /// * `amount` - The amount of the input being spent.
+    /// * `tx_to` - The transaction containing the script.
+    /// * `input_index` - The index of the input to verify.
+    /// * `flags` - Script verification flags.
+    /// * `spent_outputs` - The outputs being spent by the transaction.
+    ///
+    /// # Errors
+    /// Returns `KernelError` if verification fails.
+    fn verify(
+        &self,
+        script_pubkey: &[u8],
+        amount: Option<i64>,
+        tx_to: &[u8],
+        input_index: u32,
+        flags: Option<u32>,
+        spent_outputs: &[TxOut],
+    ) -> Result<(), Error>;
+}
+
+/// The default `Verifier` implementation that uses `bitcoinkernel`.
+pub struct DefaultVerifier;
+```
+
+### Convert emulated transaction
+
+```rust
+/// Verifies an emulated Bitcoin script and signs the corresponding transaction.
+///
+/// This function performs script verification using bitcoinkernel, verifying an
+/// emulated P2TR input. If successful, it derives an XOnlyPublicKey from the
+/// parent key and the emulated merkle root, which is then tweaked with an optional
+/// backup merkle root to derive the actual spent UTXO, which is then key path signed
+/// with `SIGHASH_DEFAULT`.
+///
+/// # Arguments
+/// * `verifier` - The verifier to use for script validation
+/// * `emulated_script_pubkey` - The P2TR script to verify against
+/// * `amount` - The amount for the input
+/// * `emulated_tx_to` - Serialized transaction to verify and sign
+/// * `input_index` - Index of the input to verify and sign (0-based)
+/// * `emulated_spent_outputs` - Outputs being spent in the emulated transaction
+/// * `actual_spent_outputs` - Actual outputs for signature generation
+/// * `aux_rand` - Auxiliary random data for signing
+/// * `parent_key` - Parent secret key used to derive child key for signing
+/// * `backup_merkle_root` - Optional merkle root for backup script path spending
+///
+/// # Errors
+/// Returns error if verification fails, key derivation fails, or signing fails
+pub fn verify_and_sign<V: Verifier>(
+    verifier: &V,
+    emulated_script_pubkey: &[u8],
+    amount: i64,
+    emulated_tx_to: &[u8],
+    input_index: u32,
+    emulated_spent_outputs: &[TxOut],
+    actual_spent_outputs: &[TxOut],
+    aux_rand: &[u8; 32],
+    parent_key: SecretKey,
+    backup_merkle_root: Option<TapNodeHash>,
+) -> Result<Transaction, Error>;
+```
+
+### Generate an address
+
+```rust
+/// Generates P2TR address from a parent public key and the emulated merkle root,
+/// with an optional backup merkle root.
+///
+/// # Arguments
+/// * `parent_key` - The parent public key
+/// * `emulated_merkle_root` - The merkle root of the emulated input
+/// * `backup_merkle_root` - Optional merkle root for backup script path spending
+/// * `network` - The network to generate the address for
+///
+/// # Errors
+/// Returns an error if key derivation fails
+fn generate_address(
+    parent_key: PublicKey,
+    emulated_merkle_root: TapNodeHash,
+    backup_merkle_root: Option<TapNodeHash>,
+    network: Network,
+) -> Result<Address, secp256k1::Error>;
+```
+
+## Testing
+The default `Verifier` implementation is based on `bitcoinkernel`, which is an optional feature but required to run the included tests.
+
+Use the following command to run the test suite:
+
+```bash
+cargo test --features bitcoinkernel
+```
+
+Or run:
+
+```bash
+cargo test --all-features
+```
+
+## License
+
+This project is licensed under the CC0-1.0 License.
+
+## Author
+
+Joshua Doman <joshsdoman@gmail.com>