@btc-vision/btc-runtime 1.9.16 → 1.10.0

package/runtime/contracts/OP721.ts

@@ -25,7 +25,13 @@ import { IOP721 } from './interfaces/IOP721';
 import { OP721InitParameters } from './interfaces/OP721InitParameters';
 import { ReentrancyGuard } from './ReentrancyGuard';
 import { StoredMapU256 } from '../storage/maps/StoredMapU256';
-import { ApprovedEvent, ApprovedForAllEvent, MAX_URI_LENGTH, TransferredEvent, URIEvent } from '../events/predefined';
+import {
+    ApprovedEvent,
+    ApprovedForAllEvent,
+    MAX_URI_LENGTH,
+    TransferredEvent,
+    URIEvent,
+} from '../events/predefined';
 import {
     ON_OP721_RECEIVED_SELECTOR,
     OP712_DOMAIN_TYPE_HASH,
@@ -555,7 +561,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
     }
 
     protected _mint(to: Address, tokenId: u256): void {
-        if (to === Address.zero() || to === Address.dead()) {
+        if (to === Address.zero()) {
             throw new Revert('Cannot mint to zero address');
         }
         if (this._exists(tokenId)) {
@@ -630,7 +636,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
             throw new Revert('Transfer from incorrect owner');
         }
 
-        if (to === Address.zero() || to === Address.dead()) {
+        if (to === Address.zero()) {
             throw new Revert('Transfer to zero address');
         }
 
@@ -717,7 +723,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
     }
 
     protected _balanceOf(owner: Address): u256 {
-        if (owner === Address.zero() || owner === Address.dead()) {
+        if (owner === Address.zero()) {
             throw new Revert('Invalid address');
         }
         return this.balanceOfMap.get(owner);
@@ -755,10 +761,10 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
     ): void {
         const calldata = new BytesWriter(
             SELECTOR_BYTE_LENGTH +
-            ADDRESS_BYTE_LENGTH * 2 +
-            U256_BYTE_LENGTH +
-            U32_BYTE_LENGTH +
-            data.length,
+                ADDRESS_BYTE_LENGTH * 2 +
+                U256_BYTE_LENGTH +
+                U32_BYTE_LENGTH +
+                data.length,
         );
         calldata.writeSelector(ON_OP721_RECEIVED_SELECTOR);
         calldata.writeAddress(Blockchain.tx.sender);
@@ -955,7 +961,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
     protected _addressFromU256(value: u256): Address {
         // Convert u256 back to 32-byte address
         const bytes = value.toUint8Array(true); // Returns 32 bytes in BE
-        const addr = new Address();
+        const addr = new Address([]);
 
         // Direct copy since both are 32 bytes
         for (let i: i32 = 0; i < 32; i++) {

package/runtime/env/BlockchainEnvironment.ts

@@ -23,7 +23,7 @@ import {
     tLoadPointer,
     tStorePointer,
     validateBitcoinAddress,
-    verifySchnorrSignature,
+    verifySignature,
 } from './global';
 import { eqUint, MapUint8Array } from '../generic/MapUint8Array';
 import { EMPTY_BUFFER } from '../math/bytes';
@@ -32,6 +32,9 @@ import { Calldata } from '../types';
 import { Revert } from '../types/Revert';
 import { Selector } from '../math/abi';
 import { Network, Networks } from '../script/Networks';
+import { ExtendedAddress } from '../types/ExtendedAddress';
+import { SignaturesMethods } from './consensus/Signatures';
+import { MLDSAMetadata, MLDSASecurityLevel } from './consensus/MLDSAMetadata';
 
 export * from '../env/global';
 
@@ -61,7 +64,7 @@ export class BlockchainEnvironment {
      * Standard dead address for burn operations.
      * Assets sent here are permanently unrecoverable.
      */
-    public readonly DEAD_ADDRESS: Address = Address.dead();
+    public readonly DEAD_ADDRESS: ExtendedAddress = ExtendedAddress.dead();
 
     private storage: MapUint8Array = new MapUint8Array();
     private transientStorage: MapUint8Array = new MapUint8Array();
@@ -339,11 +342,15 @@ export class BlockchainEnvironment {
         const contractAddress = reader.readAddress();
         const contractDeployer = reader.readAddress();
         const caller = reader.readAddress();
-        const origin = reader.readAddress();
+        const origin = reader.readBytesArray(32);
         const chainId = reader.readBytes(32);
         const protocolId = reader.readBytes(32);
+        const tweakedPublicKey = reader.readBytesArray(ADDRESS_BYTE_LENGTH);
+        const consensusFlags = reader.readU64();
 
-        this._tx = new Transaction(caller, origin, txId, txHash);
+        const originAddress = new ExtendedAddress(tweakedPublicKey, origin);
+
+        this._tx = new Transaction(caller, originAddress, txId, txHash, consensusFlags);
         this._contractDeployer = contractDeployer;
         this._contractAddress = contractAddress;
         this._chainId = chainId;
@@ -650,6 +657,10 @@ export class BlockchainEnvironment {
      *          - Linear aggregation properties
      *          - Used in Taproot (post-2021)
      *
+     * @deprecated Use Blockchain.verifySignature() instead for automatic consensus migration.
+     *            verifySignature() supports both Schnorr and ML-DSA signatures with proper
+     *            consensus flag handling for quantum resistance transitions.
+     *
      * @example
      * ```typescript
      * const isValid = Blockchain.verifySchnorrSignature(
@@ -665,10 +676,170 @@ export class BlockchainEnvironment {
         signature: Uint8Array,
         hash: Uint8Array,
     ): boolean {
-        const result: u32 = verifySchnorrSignature(publicKey.buffer, signature.buffer, hash.buffer);
+        WARNING(
+            'verifySchnorrSignature is deprecated. Use verifySignature() for consensus-aware signature verification and quantum resistance support.',
+        );
+
+        return this.internalVerifySchnorr(publicKey, signature, hash);
+    }
+
+    /**
+     * Verifies an ML-DSA signature (quantum-resistant).
+     *
+     * @param level - Security level (MLDSASecurityLevel.Level2: ML-DSA-44, MLDSASecurityLevel.Level3: ML-DSA-65, MLDSASecurityLevel.Level5: ML-DSA-87)
+     * @param publicKey - ML-DSA public key (1312/1952/2592 bytes based on level)
+     * @param signature - ML-DSA signature (2420/3309/4627 bytes based on level)
+     * @param hash - 32-byte message hash
+     * @returns true if signature is valid
+     *
+     * @warning ML-DSA provides quantum resistance:
+     *          - NIST standardized lattice-based signatures
+     *          - Larger keys/signatures than classical algorithms
+     *          - Security levels: 2 (ML-DSA-44), 3 (ML-DSA-65), 5 (ML-DSA-87)
+     *
+     * @throws {Revert} If public key length doesn't match level
+     * @throws {Revert} If signature length doesn't match level
+     * @throws {Revert} If hash is not 32 bytes
+     *
+     * @example
+     * ```typescript
+     * // ML-DSA-44 (security level 2)
+     * const isValid = Blockchain.verifyMLDSASignature(
+     *     MLDSASecurityLevel.Level2, // level 0 = ML-DSA-44
+     *     mldsaPublicKey, // 1312 bytes
+     *     mldsaSignature, // 2420 bytes
+     *     messageHash // 32 bytes
+     * );
+     * if (!isValid) throw new Revert("Invalid ML-DSA signature");
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // ML-DSA-87 (highest security level 5)
+     * const isValid = Blockchain.verifyMLDSASignature(
+     *     MLDSASecurityLevel.Level5, // level 2 = ML-DSA-87
+     *     mldsaPublicKey, // 2592 bytes
+     *     mldsaSignature, // 4627 bytes
+     *     messageHash // 32 bytes
+     * );
+     * ```
+     */
+    public verifyMLDSASignature(
+        level: MLDSASecurityLevel,
+        publicKey: Uint8Array,
+        signature: Uint8Array,
+        hash: Uint8Array,
+    ): boolean {
+        const publicKeyLength = MLDSAMetadata.fromLevel(level);
+        if (publicKey.length !== (publicKeyLength as i32)) {
+            throw new Revert(
+                `Invalid ML-DSA public key length. Expected ${publicKeyLength}, got ${publicKey.length}`,
+            );
+        }
+
+        const signatureLength = MLDSAMetadata.signatureLen(publicKeyLength);
+        if (signature.length !== signatureLength) {
+            throw new Revert(
+                `Invalid ML-DSA signature length. Expected ${signatureLength}, got ${signature.length}`,
+            );
+        }
+
+        if (hash.length !== 32) {
+            throw new Revert(`Invalid hash length. Expected 32, got ${hash.length}`);
+        }
+
+        const writer = new BytesWriter(2 + publicKey.length);
+        writer.writeU8(<u8>SignaturesMethods.MLDSA);
+        writer.writeU8(<u8>level);
+        writer.writeBytes(publicKey);
+
+        const result: u32 = verifySignature(
+            writer.getBuffer().buffer,
+            signature.buffer,
+            hash.buffer,
+        );
+
         return result === 1;
     }
 
+    /**
+     * Verifies a signature based on current consensus rules.
+     *
+     * This method automatically selects the appropriate signature verification algorithm
+     * based on the current consensus state:
+     *
+     * - When `unsafeSignaturesAllowed()` returns `true`: Uses Schnorr signatures (quantum-vulnerable)
+     * - When `unsafeSignaturesAllowed()` returns `false`: Uses ML-DSA signatures (quantum-resistant)
+     *
+     * The `unsafeSignaturesAllowed()` flag indicates whether the network is still accepting
+     * legacy Schnorr signatures. This flag will be `true` during the transition period to
+     * maintain backwards compatibility with existing infrastructure. Once the network completes
+     * its quantum-resistant upgrade, this flag will permanently become `false`, enforcing
+     * ML-DSA signatures exclusively.
+     *
+     * @param address - The address containing the public key(s) to verify against.
+     *                  For Schnorr, uses the taproot tweaked public key.
+     *                  For ML-DSA, uses the ML-DSA public key component.
+     * @param signature - The signature bytes to verify. Format depends on algorithm:
+     *                    - Schnorr: 64-byte signature
+     *                    - ML-DSA-44 (Level 2): 2420 bytes
+     *                    - ML-DSA-65 (Level 3): 3309 bytes
+     *                    - ML-DSA-87 (Level 5): 4627 bytes
+     * @param hash - The 32-byte message hash that was signed. Usually a SHA256 hash
+     *               of the transaction data or message being verified.
+     *
+     * @param forceMLDSA - Optional flag to force ML-DSA verification even if Schnorr is allowed.
+     *
+     * @returns `true` if the signature is valid for the given address and hash,
+     *          `false` if verification fails or if the signature format is invalid
+     *
+     * @throws May throw if the signature or hash have invalid lengths for the selected
+     *         algorithm, though implementations should generally return false instead
+     *
+     * @remarks
+     * The consensus rules determine which signature scheme is active:
+     * - Pre-quantum era: Schnorr signatures (Bitcoin taproot compatible)
+     * - Post-quantum era: ML-DSA Level 2 (NIST standardized, 128-bit quantum security)
+     *
+     *  ML-DSA Level 2 (ML-DSA-44) corresponds to NIST security category 2, providing security
+     *  equivalent to AES-128 against both classical and quantum attacks. Its security is based on
+     *  the hardness of underlying lattice problems and is designed to resist attacks from quantum
+     *  computers, including both Shor's algorithm (which breaks RSA/ECC) and Grover's algorithm
+     *  (which reduces symmetric key security). The security levels (2, 3, 5) correspond to the
+     *  number of quantum gates required for Grover's algorithm to break them, equivalent to
+     *  AES-128, AES-192, and AES-256 respectively.
+     *
+     * @example
+     * ```typescript
+     * const isValid = contract.verifySignature(
+     *     senderAddress,
+     *     signatureBytes,
+     *     transactionHash
+     * );
+     * if (!isValid) {
+     *     throw new Error("Invalid signature");
+     * }
+     * ```
+     */
+    public verifySignature(
+        address: Address,
+        signature: Uint8Array,
+        hash: Uint8Array,
+        forceMLDSA: boolean = false,
+    ): boolean {
+        if (this.tx.consensus.unsafeSignaturesAllowed() && !forceMLDSA) {
+            return this.internalVerifySchnorr(address, signature, hash);
+        } else {
+            // Default to ML-DSA Level 2 (ML-DSA-44) for quantum resistance
+            return this.verifyMLDSASignature(
+                MLDSASecurityLevel.Level2,
+                address.mldsaPublicKey,
+                signature,
+                hash,
+            );
+        }
+    }
+
     /**
      * Checks if an address is a contract (not an EOA).
      *
@@ -809,6 +980,32 @@ export class BlockchainEnvironment {
         return Uint8Array.wrap(hash);
     }
 
+    private internalVerifySchnorr(
+        publicKey: Address,
+        signature: Uint8Array,
+        hash: Uint8Array,
+    ): boolean {
+        if (signature.byteLength !== 64) {
+            throw new Revert(`Invalid signature length. Expected 64, got ${signature.length}`);
+        }
+
+        if (hash.byteLength !== 32) {
+            throw new Revert(`Invalid hash length. Expected 32, got ${hash.length}`);
+        }
+
+        const writer = new BytesWriter(1 + ADDRESS_BYTE_LENGTH);
+        writer.writeU8(<u8>SignaturesMethods.Schnorr);
+        writer.writeAddress(publicKey);
+
+        const result: u32 = verifySignature(
+            writer.getBuffer().buffer,
+            signature.buffer,
+            hash.buffer,
+        );
+
+        return result === 1;
+    }
+
     private createContractIfNotExists(): void {
         if (!this._contract) {
             throw new Revert('Contract is required');

package/runtime/env/classes/Transaction.ts

@@ -4,17 +4,50 @@ import { Potential } from '../../lang/Definitions';
 import { BytesReader } from '../../buffer/BytesReader';
 import { getInputsSize, getOutputsSize, inputs, outputs } from '../global';
 import { TransactionDecoder } from '../decoders/TransactionDecoder';
+import { ConsensusRules } from '../consensus/ConsensusRules';
+import { ExtendedAddress } from '../../types/ExtendedAddress';
 
 @final
 export class Transaction {
+    public readonly consensus: ConsensusRules;
+
+    /**
+     * The `sender` is the immediate caller of this transaction, which may be a contract or a user.
+     * It is always typed as `Address`, which may not be quantum-resistant.
+     *
+     * The `origin` is the original transaction signer (the "leftmost" entity in the call chain).
+     * It is typed as `ExtendedAddress`, allowing for both Schnorr and ML-DSA keys (including quantum-resistant keys).
+     *
+     * This distinction is intentional: only the transaction originator may use quantum-resistant keys,
+     * while intermediate contract callers are always standard addresses. This should be considered when
+     * performing address verification or signature checks.
+     */
+    public readonly sender: Address;
+
+    /**
+     * The `origin` is the original transaction signer (the "leftmost" entity in the call chain).
+     * It is typed as `ExtendedAddress`, allowing for both Schnorr and ML-DSA keys (including quantum-resistant keys).
+     *
+     * This distinction is intentional: only the transaction originator may use quantum-resistant keys,
+     * while intermediate contract callers are always standard addresses. This should be considered when
+     * performing address verification or signature checks.
+     *
+     */
+    public readonly origin: ExtendedAddress;
+
     private readonly transactionDecoder: TransactionDecoder = new TransactionDecoder();
 
     public constructor(
-        public readonly sender: Address, // "immediate caller"
-        public readonly origin: Address, // "leftmost thing in the call chain"
+        sender: Address, // "immediate caller"
+        origin: ExtendedAddress, // "leftmost thing in the call chain"
         public readonly txId: Uint8Array,
         public readonly hash: Uint8Array,
-    ) {}
+        consensusFlags: u64,
+    ) {
+        this.sender = sender;
+        this.origin = origin;
+        this.consensus = new ConsensusRules(consensusFlags);
+    }
 
     private _inputs: Potential<TransactionInput[]> = null;
 

package/runtime/env/consensus/ConsensusRules.ts

@@ -0,0 +1,228 @@
+/**
+ * Consensus flags for protocol behavior control
+ */
+@final
+export class ConsensusRules {
+    // Flag constants
+    public static readonly NONE: u64 = 0b00000000;
+    public static readonly UNSAFE_QUANTUM_SIGNATURES_ALLOWED: u64 = 0b00000001;
+    public static readonly RESERVED_FLAG_1: u64 = 0b00000010;
+    public static readonly RESERVED_FLAG_2: u64 = 0b00000100;
+
+    private value: u64;
+
+    constructor(value: u64 = 0) {
+        this.value = value;
+    }
+
+    /**
+     * Creates a new empty ConsensusRules
+     */
+    public static new(): ConsensusRules {
+        return new ConsensusRules(0);
+    }
+
+    /**
+     * Creates ConsensusRules from u64 value
+     */
+    public static fromU64(value: u64): ConsensusRules {
+        return new ConsensusRules(value);
+    }
+
+    /**
+     * Helper to create flags from multiple flag values
+     */
+    public static combine(flags: u64[]): ConsensusRules {
+        let result: u64 = 0;
+        for (let i = 0; i < flags.length; i++) {
+            result |= flags[i];
+        }
+        return new ConsensusRules(result);
+    }
+
+    /**
+     * Gets the underlying u64 value
+     */
+    public asU64(): u64 {
+        return this.value;
+    }
+
+    /**
+     * Converts to big-endian byte array
+     */
+    public toBeBytes(): Uint8Array {
+        const bytes = new Uint8Array(8);
+        const view = new DataView(bytes.buffer);
+        view.setUint64(0, this.value, false); // false = big-endian
+        return bytes;
+    }
+
+    /**
+     * Checks if all flags in 'other' are set
+     */
+    public contains(other: ConsensusRules): boolean {
+        return (this.value & other.value) == other.value;
+    }
+
+    /**
+     * Checks if flag value is set
+     */
+    public containsFlag(flag: u64): boolean {
+        return (this.value & flag) == flag;
+    }
+
+    /**
+     * Checks if any flags in 'other' are set
+     */
+    public intersects(other: ConsensusRules): boolean {
+        return (this.value & other.value) != 0;
+    }
+
+    /**
+     * Checks if any flag value is set
+     */
+    public intersectsFlag(flag: u64): boolean {
+        return (this.value & flag) != 0;
+    }
+
+    /**
+     * Checks if no flags are set
+     */
+    public isEmpty(): boolean {
+        return this.value == 0;
+    }
+
+    /**
+     * Returns union of flags
+     */
+    public union(other: ConsensusRules): ConsensusRules {
+        return new ConsensusRules(this.value | other.value);
+    }
+
+    /**
+     * Returns intersection of flags
+     */
+    public intersection(other: ConsensusRules): ConsensusRules {
+        return new ConsensusRules(this.value & other.value);
+    }
+
+    /**
+     * Returns difference of flags (flags in this but not in other)
+     */
+    public difference(other: ConsensusRules): ConsensusRules {
+        return new ConsensusRules(this.value & ~other.value);
+    }
+
+    /**
+     * Returns symmetric difference of flags
+     */
+    public symmetricDifference(other: ConsensusRules): ConsensusRules {
+        return new ConsensusRules(this.value ^ other.value);
+    }
+
+    /**
+     * Returns complement of flags
+     */
+    public complement(): ConsensusRules {
+        return new ConsensusRules(~this.value);
+    }
+
+    /**
+     * Inserts flags from other
+     */
+    public insert(other: ConsensusRules): void {
+        this.value |= other.value;
+    }
+
+    /**
+     * Inserts a flag value
+     */
+    public insertFlag(flag: u64): void {
+        this.value |= flag;
+    }
+
+    /**
+     * Removes flags from other
+     */
+    public remove(other: ConsensusRules): void {
+        this.value &= ~other.value;
+    }
+
+    /**
+     * Removes a flag value
+     */
+    public removeFlag(flag: u64): void {
+        this.value &= ~flag;
+    }
+
+    /**
+     * Toggles flags from other
+     */
+    public toggle(other: ConsensusRules): void {
+        this.value ^= other.value;
+    }
+
+    /**
+     * Toggles a flag value
+     */
+    public toggleFlag(flag: u64): void {
+        this.value ^= flag;
+    }
+
+    /**
+     * Sets or clears flags based on value
+     */
+    public set(other: ConsensusRules, value: boolean): void {
+        if (value) {
+            this.insert(other);
+        } else {
+            this.remove(other);
+        }
+    }
+
+    /**
+     * Sets or clears a flag based on value
+     */
+    public setFlag(flag: u64, value: boolean): void {
+        if (value) {
+            this.insertFlag(flag);
+        } else {
+            this.removeFlag(flag);
+        }
+    }
+
+    /**
+     * Creates a copy of this ConsensusFlags
+     */
+    public clone(): ConsensusRules {
+        return new ConsensusRules(this.value);
+    }
+
+    /**
+     * Checks equality with another ConsensusFlags
+     */
+    public equals(other: ConsensusRules): boolean {
+        return this.value == other.value;
+    }
+
+    /**
+     * Returns binary string representation
+     */
+    public toBinaryString(): string {
+        let result = '';
+        let val = this.value;
+        for (let i = 0; i < 64; i++) {
+            result = (val & 1 ? '1' : '0') + result;
+            val = val >> 1;
+        }
+        return '0b' + result;
+    }
+
+    public unsafeSignaturesAllowed(): boolean {
+        return this.containsFlag(ConsensusRules.UNSAFE_QUANTUM_SIGNATURES_ALLOWED);
+    }
+}
+
+export function createConsensusFlags(flags: u64[]): ConsensusRules {
+    return ConsensusRules.combine(flags);
+}