@btc-vision/btc-runtime 1.9.16 → 1.10.1

package/runtime/types/ExtendedAddress.ts

@@ -0,0 +1,426 @@
+import { Potential } from '../lang/Definitions';
+import { decodeHexArray } from '../utils';
+import { Blockchain } from '../env';
+import { Network } from '../script/Networks';
+import { Address } from './Address';
+import { BitcoinAddresses } from '../script/BitcoinAddresses';
+
+/**
+ * Extended address implementation for Bitcoin with dual-key support.
+ *
+ * ExtendedAddress combines both Schnorr (taproot) and ML-DSA public keys to provide
+ * a migration path from classical to quantum-resistant cryptography. The address
+ * stores the ML-DSA public key hash (inherited from Address) and additionally
+ * maintains the tweaked Schnorr public key for Bitcoin taproot compatibility.
+ *
+ * @remarks
+ * This class is marked as @final and cannot be extended. It represents the complete
+ * address format for OPNet's quantum-resistant transition, supporting both legacy
+ * Schnorr signatures and future ML-DSA signatures within the same address structure.
+ *
+ * The tweaked public key enables P2TR (pay-to-taproot) address generation while
+ * the ML-DSA key hash provides quantum resistance when consensus transitions.
+ *
+ * @example
+ * ```typescript
+ * // Create from hex strings
+ * const addr = ExtendedAddress.fromStringPair(
+ *   '0x' + '11'.repeat(32), // tweaked Schnorr key
+ *   '0x' + '22'.repeat(32)  // ML-DSA key hash
+ * );
+ *
+ * // Generate P2TR address
+ * const bitcoinAddr = addr.p2tr();
+ *
+ * // Check if address is dead/zero
+ * if (addr.isDead()) {
+ *   // Handle dead address
+ * }
+ * ```
+ */
+@final
+export class ExtendedAddress extends Address {
+    /**
+     * The 32-byte tweaked Schnorr public key for taproot compatibility.
+     * This key is used for P2TR address generation and Schnorr signature verification.
+     */
+    private readonly tweakedPublicKey: Uint8Array;
+
+    /**
+     * Creates a new ExtendedAddress instance.
+     *
+     * @param tweakedPublicKey - 32-byte tweaked Schnorr public key for taproot
+     * @param publicKey - 32-byte ML-DSA public key hash (SHA256 of full ML-DSA key)
+     *
+     * @throws {Error} If tweakedPublicKey is not exactly 32 bytes
+     * @throws {Error} If publicKey is not exactly 32 bytes (thrown by parent class)
+     */
+    public constructor(tweakedPublicKey: u8[], publicKey: u8[]) {
+        super(publicKey);
+
+        if (tweakedPublicKey.length !== 32) {
+            throw new Error('Tweaked public key must be 32 bytes long');
+        }
+
+        this.tweakedPublicKey = new Uint8Array(32);
+        this.tweakedPublicKey.set(tweakedPublicKey);
+    }
+
+    /**
+     * Returns the canonical dead address.
+     *
+     * The dead address (284ae4acdb32a99ba3ebfa66a91ddb41a7b7a1d2fef415399922cd8a04485c02)
+     * is generated from the uncompressed public key:
+     * 04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f
+     *
+     * This address is commonly used as a burn address or null recipient in contracts.
+     *
+     * @returns A clone of the predefined DEAD_ADDRESS constant
+     *
+     * @example
+     * ```typescript
+     * const burnAddr = ExtendedAddress.dead();
+     * if (recipient.isDead()) {
+     *   // Tokens are being burned
+     * }
+     * ```
+     */
+    public static dead(): ExtendedAddress {
+        return DEAD_ADDRESS.clone();
+    }
+
+    /**
+     * Returns the zero address with all bytes set to 0x00.
+     *
+     * @returns A clone of the predefined ZERO_BITCOIN_ADDRESS constant
+     *
+     * @example
+     * ```typescript
+     * const zero = ExtendedAddress.zero();
+     * if (addr.isZero()) {
+     *   // Handle uninitialized address
+     * }
+     * ```
+     */
+    public static zero(): ExtendedAddress {
+        return ZERO_BITCOIN_ADDRESS.clone();
+    }
+
+    /**
+     * Disabled method - use fromStringPair instead.
+     *
+     * This method is intentionally disabled for ExtendedAddress to prevent
+     * accidental creation with only one key. ExtendedAddress requires both
+     * the tweaked Schnorr key and ML-DSA key hash for proper functionality.
+     *
+     * @param _ - Unused parameter
+     *
+     * @throws {Error} Always throws with instruction to use fromStringPair
+     *
+     * @deprecated Use {@link fromStringPair} instead
+     */
+    public static override fromString(_: string): ExtendedAddress {
+        ERROR(
+            `Use ExtendedAddress.fromStringPair instead. This method is disabled. You must provide both the tweaked public key and the ML-DSA public key.`,
+        );
+    }
+
+    /**
+     * Creates an ExtendedAddress from hexadecimal string representations of both keys.
+     *
+     * This is the preferred factory method for creating ExtendedAddress instances when
+     * both the Schnorr tweaked public key and ML-DSA public key are available as strings.
+     * Unlike the single-parameter fromString method (which maintains backward compatibility
+     * with the base Address class), this method properly initializes both key components
+     * required for full ExtendedAddress functionality.
+     *
+     * @param tweakedPubKey - The 32-byte Schnorr tweaked public key as a hexadecimal string.
+     *                        Can be prefixed with '0x' or unprefixed. Must decode to exactly
+     *                        32 bytes for taproot compatibility.
+     * @param mldsaPubKey - The 32-byte ML-DSA public key hash (SHA256 of the full ML-DSA public key)
+     *                      as a hexadecimal string. Can be prefixed with '0x' or unprefixed.
+     *                      Must decode to exactly 32 bytes for address derivation.
+     *
+     * @returns A new ExtendedAddress instance with both keys properly initialized
+     *
+     * @throws {Error} If tweakedPubKey doesn't decode to exactly 32 bytes
+     * @throws {Error} If mldsaPubKey doesn't decode to exactly 32 bytes
+     * @throws {Error} If either string contains invalid hexadecimal characters
+     *
+     * @example
+     * ```typescript
+     * // With 0x prefix
+     * const addr1 = ExtendedAddress.fromStringPair(
+     *   '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+     *   '0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210'
+     * );
+     *
+     * // Without 0x prefix
+     * const addr2 = ExtendedAddress.fromStringPair(
+     *   '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+     *   'fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210'
+     * );
+     * ```
+     *
+     * @remarks
+     * For quantum-resistant applications, ensure the mldsaPubKey parameter is the SHA256 hash
+     * of a valid ML-DSA-44 (Level 2) public key. The full ML-DSA public key will be loaded
+     * from storage when needed for signature verification.
+     *
+     * @see {@link fromUint8Array} for binary initialization with concatenated keys
+     */
+    public static fromStringPair(tweakedPubKey: string, mldsaPubKey: string): ExtendedAddress {
+        if (tweakedPubKey.startsWith('0x')) {
+            tweakedPubKey = tweakedPubKey.slice(2);
+        }
+
+        if (mldsaPubKey.startsWith('0x')) {
+            mldsaPubKey = mldsaPubKey.slice(2);
+        }
+
+        return new ExtendedAddress(decodeHexArray(tweakedPubKey), decodeHexArray(mldsaPubKey));
+    }
+
+    /**
+     * Creates an ExtendedAddress from a concatenated 64-byte array.
+     *
+     * The input must contain exactly 64 bytes: the first 32 bytes are the tweaked
+     * Schnorr public key, followed by 32 bytes of the ML-DSA public key hash.
+     *
+     * @param bytes - A 64-byte Uint8Array containing both keys concatenated
+     *
+     * @returns A new ExtendedAddress instance
+     *
+     * @throws {Error} If the input is not exactly 64 bytes
+     *
+     * @example
+     * ```typescript
+     * const combined = new Uint8Array(64);
+     * combined.set(tweakedKey, 0);
+     * combined.set(mldsaKeyHash, 32);
+     * const addr = ExtendedAddress.fromUint8Array(combined);
+     * ```
+     */
+    public static fromUint8Array(bytes: Uint8Array): ExtendedAddress {
+        if (bytes.length !== 64) {
+            throw new Error('Expected 64 bytes: 32 for tweakedPublicKey, 32 for publicKey');
+        }
+
+        const tweakedPublicKey: u8[] = new Array<u8>(32);
+        const publicKey: u8[] = new Array<u8>(32);
+
+        for (let i = 0; i < 32; i++) {
+            tweakedPublicKey[i] = bytes[i];
+            publicKey[i] = bytes[32 + i];
+        }
+
+        return new ExtendedAddress(tweakedPublicKey, publicKey);
+    }
+
+    /**
+     * Generates a CSV (CheckSequenceVerify) timelocked P2WSH address.
+     *
+     * Creates a Bitcoin address that requires both the specified number of blocks
+     * to pass and the correct signature to spend funds. Used for timelocked
+     * liquidity provisions in NativeSwap and similar protocols.
+     *
+     * @param address - The address bytes to create CSV lock for
+     * @param blocks - Number of blocks for the CSV timelock
+     *
+     * @returns The generated P2WSH address string with CSV timelock
+     *
+     * @example
+     * ```typescript
+     * // Create 144-block (approximately 1 day) timelock
+     * const timelocked = ExtendedAddress.toCSV(addr.toBytes(), 144);
+     * ```
+     */
+    public static toCSV(address: Uint8Array, blocks: u32): string {
+        return BitcoinAddresses.csvP2wshAddress(address, blocks, Network.hrp(Blockchain.network))
+            .address;
+    }
+
+    /**
+     * Generates a P2WPKH (pay-to-witness-public-key-hash) address.
+     *
+     * Creates a native SegWit address (bc1...) from the provided address bytes.
+     * This is the standard Bitcoin address format for SegWit transactions.
+     *
+     * @param address - The address bytes to encode
+     *
+     * @returns The bech32-encoded P2WPKH address string
+     *
+     * @example
+     * ```typescript
+     * const segwitAddr = ExtendedAddress.p2wpkh(addr.toBytes());
+     * // Returns: "bc1q..." on mainnet or "tb1q..." on testnet
+     * ```
+     */
+    public static p2wpkh(address: Uint8Array): string {
+        return BitcoinAddresses.p2wpkh(address, Network.hrp(Blockchain.network));
+    }
+
+    /**
+     * Downcasts this ExtendedAddress to a base Address.
+     *
+     * Returns this instance as the base Address type, maintaining only
+     * the ML-DSA public key hash and losing access to the tweaked key.
+     *
+     * @returns This instance cast as Address
+     *
+     * @remarks
+     * The returned Address still contains the same data but without
+     * access to ExtendedAddress-specific methods and the tweaked key.
+     */
+    public downCast(): Address {
+        return this;
+    }
+
+    /**
+     * Checks if all bytes of the ML-DSA key hash are zero.
+     *
+     * @returns `true` if the ML-DSA key hash is all zeros, `false` otherwise
+     *
+     * @remarks
+     * This only checks the ML-DSA key hash portion (inherited from Address),
+     * not the tweaked Schnorr key. Use ZERO_BITCOIN_ADDRESS for a fully
+     * zero ExtendedAddress.
+     */
+    public isZero(): bool {
+        for (let i = 0; i < this.length; i++) {
+            if (this[i] != 0) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Checks if this address equals the canonical dead address.
+     *
+     * @returns `true` if this address matches DEAD_ADDRESS, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * if (recipient.isDead()) {
+     *   // Funds are being burned
+     *   return;
+     * }
+     * ```
+     */
+    public isDead(): bool {
+        for (let i = 0; i < this.length; i++) {
+            if (this[i] != DEAD_ADDRESS[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Generates the P2TR (pay-to-taproot) address for this ExtendedAddress.
+     *
+     * Uses the tweaked Schnorr public key to create a taproot address
+     * following BIP341 specifications. This is the primary Bitcoin address
+     * format for this ExtendedAddress.
+     *
+     * @returns The bech32m-encoded P2TR address string
+     *
+     * @example
+     * ```typescript
+     * const taprootAddr = addr.p2tr();
+     * // Returns: "bc1p..." on mainnet or "tb1p..." on testnet
+     * ```
+     *
+     * @remarks
+     * The address is generated from the tweaked public key only.
+     * The ML-DSA key hash is not used in P2TR address generation.
+     */
+    public p2tr(): string {
+        return BitcoinAddresses.p2trKeyPathAddress(
+            this.tweakedPublicKey,
+            Network.hrp(Blockchain.network),
+        );
+    }
+
+    /**
+     * Returns the P2TR address string representation.
+     *
+     * @returns The P2TR address (delegates to p2tr())
+     *
+     * @override Overrides the base Address.toString() which returns hex
+     */
+    public toString(): string {
+        return this.p2tr();
+    }
+
+    /**
+     * Creates a deep copy of this ExtendedAddress.
+     *
+     * @returns A new ExtendedAddress instance with identical data
+     *
+     * @override Overrides Address.clone() to return ExtendedAddress type
+     *
+     * @remarks
+     * Both the tweaked Schnorr key and ML-DSA key hash are cloned.
+     * The isDefined flag state is also preserved in the clone.
+     */
+    public override clone(): ExtendedAddress {
+        // Convert Uint8Array to u8[] for the tweakedPublicKey
+        const tweakedKeyArray: u8[] = new Array<u8>(this.tweakedPublicKey.length);
+        for (let i = 0; i < this.tweakedPublicKey.length; i++) {
+            tweakedKeyArray[i] = this.tweakedPublicKey[i];
+        }
+
+        // Convert the address bytes (this.slice(0)) to u8[]
+        const addressSlice = this.slice(0);
+        const addressArray: u8[] = new Array<u8>(addressSlice.length);
+        for (let i = 0; i < addressSlice.length; i++) {
+            addressArray[i] = addressSlice[i];
+        }
+
+        const cloned = new ExtendedAddress(tweakedKeyArray, addressArray);
+
+        // Duplicate the isDefined flag as well:
+        cloned.isDefined = this.isDefined;
+
+        return cloned;
+    }
+}
+
+/**
+ * Pre-initialized zero ExtendedAddress constant.
+ * Both the tweaked key and ML-DSA key hash are all zeros.
+ */
+export const ZERO_BITCOIN_ADDRESS: ExtendedAddress = new ExtendedAddress(
+    [
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+        0,
+    ],
+    [
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+        0,
+    ],
+);
+
+/**
+ * Pre-initialized dead ExtendedAddress constant.
+ * The tweaked key is zero while the ML-DSA key hash represents the canonical dead address.
+ * Hash: 284ae4acdb32a99ba3ebfa66a91ddb41a7b7a1d2fef415399922cd8a04485c02
+ */
+export const DEAD_ADDRESS: ExtendedAddress = new ExtendedAddress(
+    [
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+        0,
+    ],
+    [
+        40, 74, 228, 172, 219, 50, 169, 155, 163, 235, 250, 102, 169, 29, 219, 65, 167, 183, 161,
+        210, 254, 244, 21, 57, 153, 34, 205, 138, 4, 72, 92, 2,
+    ],
+);
+
+/**
+ * Type alias for nullable ExtendedAddress references.
+ */
+export declare type PotentialBitcoinAddress = Potential<ExtendedAddress>;

package/runtime/nested/PointerManager.ts

@@ -1,55 +0,0 @@
-import { Blockchain } from '../env';
-import { Potential } from '../lang/Definitions';
-import { bigEndianAdd } from '../math/bytes';
-import { Plugin } from '../plugins/Plugin';
-
-/**
- * A unique key in storage that holds the next free "offset" as a 256-bit counter.
- * You can change this to any 32-byte constant you like.
- */
-const ALLOCATOR_KEY = new Uint8Array(32);
-for (let i = 0; i < 32; i++) {
-    ALLOCATOR_KEY[i] = 0xff;
-}
-
-/**
- * PointerManager: ensures we never collide while allocating variable-length data.
- * - We store a global "offset" in ALLOCATOR_KEY (as a big-endian u256).
- * - Each time we allocate N slots (N * 32 bytes), we do:
- *      oldOffset = currentGlobalOffset
- *      newOffset = oldOffset + N
- *      store newOffset back
- *      return oldOffset as the base pointer
- */
-class _PointerManager extends Plugin {
-    private _cachedOffset: Potential<Uint8Array> = null;
-
-    private get cachedOffset(): Uint8Array {
-        if (!this._cachedOffset) {
-            this._cachedOffset = Blockchain.getStorageAt(ALLOCATOR_KEY);
-        }
-
-        return this._cachedOffset as Uint8Array;
-    }
-
-    /**
-     * Allocates `numSlots` (each 32 bytes). Returns a 32-byte pointer (u256 in big-endian).
-     *
-     * Each slot is conceptually:
-     *   slot0 = pointer + 0
-     *   slot1 = pointer + 1
-     *   ...
-     * and so forth in big-endian arithmetic.
-     */
-    public allocateSlots(numSlots: u64): Uint8Array {
-        this._cachedOffset = bigEndianAdd(this.cachedOffset, numSlots);
-
-        const val = this.cachedOffset;
-        Blockchain.setStorageAt(ALLOCATOR_KEY, val);
-
-        return val;
-    }
-}
-
-export const PointerManager = new _PointerManager();
-Blockchain.registerPlugin(PointerManager);

package/runtime/nested/codecs/AddressCodec.ts

@@ -1,19 +0,0 @@
-import { ICodec } from '../interfaces/ICodec';
-import { Address } from '../../types/Address';
-
-class _AddressCodec implements ICodec<Address> {
-    public encode(value: Address): Uint8Array {
-        return value;
-    }
-
-    public decode(buffer: Uint8Array): Address {
-        if (buffer.length == 0) {
-            return Address.zero();
-        }
-
-        return Address.fromUint8Array(buffer);
-    }
-}
-
-export const idOfAddressCodec = idof<_AddressCodec>();
-export const AddressCodec = new _AddressCodec();

package/runtime/nested/codecs/BooleanCodec.ts

@@ -1,17 +0,0 @@
-import { ICodec } from '../interfaces/ICodec';
-
-class _BooleanCodec implements ICodec<bool> {
-    public encode(value: bool): Uint8Array {
-        const out = new Uint8Array(1);
-        out[0] = value ? 1 : 0;
-        return out;
-    }
-
-    public decode(buffer: Uint8Array): bool {
-        if (buffer.length == 0) return false;
-        return buffer[0] == 1;
-    }
-}
-
-export const idOfBoolCodec = idof<_BooleanCodec>();
-export const BooleanCodec = new _BooleanCodec();

package/runtime/nested/codecs/Ids.ts

@@ -1,10 +0,0 @@
-import { i128, u128, u256 } from '@btc-vision/as-bignum/assembly';
-import { Uint8Array } from 'typedarray';
-import { Address } from '../../types/Address';
-
-export const idOfU256 = idof<u256>();
-export const idOfU128 = idof<u128>();
-export const idOfI128 = idof<i128>();
-export const idOfUint8Array = idof<Uint8Array>();
-export const idOfString = idof<string>();
-export const idOfAddress = idof<Address>();

package/runtime/nested/codecs/NumericCodec.ts

@@ -1,58 +0,0 @@
-import { i128, u128, u256 } from '@btc-vision/as-bignum/assembly';
-import { ICodec } from '../interfaces/ICodec';
-import { BytesWriter } from '../../buffer/BytesWriter';
-import { BytesReader } from '../../buffer/BytesReader';
-import { idOfI128, idOfU128, idOfU256 } from './Ids';
-
-/**
- * A generic NumericCodec<T> that handles:
- *  - `u256` from @btc-vision/as-bignum (big-endian)
- *  - Any built-in integer type (i32, u32, i64, etc.) also stored big-endian
- */
-export class NumericCodec<T> implements ICodec<T> {
-    public encode(value: T): Uint8Array {
-        const id = idof<T>();
-        switch (id) {
-            case idOfU256: {
-                // T is `u256`
-                const val = changetype<u256>(value);
-                return val.toUint8Array(true); // big-endian
-            }
-            case idOfU128: {
-                // T is `u128`
-                const val = changetype<u128>(value);
-                return val.toUint8Array(true); // big-endian
-            }
-            case idOfI128: {
-                // T is `i128`
-                const val = changetype<i128>(value);
-                return val.toUint8Array(true); // big-endian
-            }
-            default: {
-                const writer = new BytesWriter(sizeof<T>());
-                writer.write<T>(value);
-
-                return writer.getBuffer();
-            }
-        }
-    }
-
-    public decode(buffer: Uint8Array): T {
-        const id = idof<T>();
-        switch (id) {
-            case idOfU256:
-                // T is `u256`
-                return changetype<T>(u256.fromBytes(buffer, true));
-            case idOfU128:
-                // T is `u128`
-                return changetype<T>(u128.fromBytes(buffer, true));
-            case idOfI128:
-                // T is `i128`
-                return changetype<T>(i128.fromBytes(buffer, true));
-            default: {
-                const writer = new BytesReader(buffer);
-                return writer.read<T>();
-            }
-        }
-    }
-}

package/runtime/nested/codecs/StringCodec.ts

@@ -1,24 +0,0 @@
-import { ICodec } from '../interfaces/ICodec';
-import { VariableBytesCodec } from './VariableBytesCodec';
-
-class IStringCodec implements ICodec<string> {
-    public encode(value: string): Uint8Array {
-        // Convert string -> UTF8 bytes
-        const utf8 = String.UTF8.encode(value, false);
-
-        // Pass to variable-bytes
-        return VariableBytesCodec.encode(Uint8Array.wrap(utf8));
-    }
-
-    public decode(buffer: Uint8Array): string {
-        const raw = VariableBytesCodec.decode(buffer);
-        if (raw.length == 0) {
-            return '';
-        }
-
-        return String.UTF8.decode(raw.buffer, false);
-    }
-}
-
-export const idOfStringCodec = idof<IStringCodec>();
-export const StringCodec = new IStringCodec();

package/runtime/nested/codecs/U256Codec.ts

@@ -1,20 +0,0 @@
-import { u256 } from '@btc-vision/as-bignum/assembly';
-import { ICodec } from '../interfaces/ICodec';
-
-class _U256Codec implements ICodec<u256> {
-    public encode(value: u256): Uint8Array {
-        // big-endian
-        return value.toUint8Array(true);
-    }
-
-    public decode(buffer: Uint8Array): u256 {
-        if (buffer.length == 0) {
-            return u256.Zero;
-        }
-
-        return u256.fromUint8ArrayBE(buffer);
-    }
-}
-
-export const idOfU256Codec = idof<_U256Codec>();
-export const U256Codec = new _U256Codec();