Add Locktime abstraction

Author: MatthewLM

coinlib/CHANGELOG.md

@@ -10,6 +10,9 @@ secp256k1-coinlib fork.
     `0xfffffffe` by default and enforce locktimes.
 - Adds `locktimeIsEnforced` to `Transaction` to determine if the locktime is in
     effect.
+- Adds `Locktime` abstractions for transactions. Transactions have
+    `.isUnlocked` to determine if the transaction is available for block
+    inclusion.
 - Moves to underlying secp256k1-coinlib.
 - Removed dependency to wasm_interop that had a broken js dependency.
 - Fixes `extraEntropy` being ignored for `Secp256k1Base.schnorrSign`.

coinlib/lib/src/coinlib_base.dart

@@ -42,6 +42,7 @@ export 'package:coinlib/src/taproot/taproot.dart';
 export 'package:coinlib/src/tx/coin_selection.dart';
 export 'package:coinlib/src/tx/transaction.dart';
 export 'package:coinlib/src/tx/sign_details.dart';
+export 'package:coinlib/src/tx/locktime.dart';
 export 'package:coinlib/src/tx/outpoint.dart';
 export 'package:coinlib/src/tx/output.dart';
 

coinlib/lib/src/tx/coin_selection.dart

@@ -5,6 +5,7 @@ import 'package:coinlib/src/tx/inputs/witness_input.dart';
 import 'package:collection/collection.dart';
 import 'inputs/input.dart';
 import 'inputs/taproot_input.dart';
+import 'locktime.dart';
 import 'output.dart';
 import 'transaction.dart';
 
@@ -48,7 +49,7 @@ class CoinSelection {
   final BigInt feePerKb;
   final BigInt minFee;
   final BigInt minChange;
-  final int locktime;
+  final Locktime locktime;
 
   /// The total value of selected inputs
   late final BigInt inputValue;
@@ -87,7 +88,7 @@ class CoinSelection {
     required this.feePerKb,
     required this.minFee,
     required this.minChange,
-    this.locktime = 0,
+    this.locktime = Locktime.zero,
   }) : selected = List.unmodifiable(selected),
     recipients = List.unmodifiable(recipients) {
 
@@ -169,7 +170,7 @@ class CoinSelection {
     required BigInt feePerKb,
     required BigInt minFee,
     required BigInt minChange,
-    int locktime = 0,
+    Locktime locktime = Locktime.zero,
   }) {
 
     final randomSelection = CoinSelection.random(
@@ -216,7 +217,7 @@ class CoinSelection {
     required BigInt feePerKb,
     required BigInt minFee,
     required BigInt minChange,
-    int locktime = 0,
+    Locktime locktime = Locktime.zero,
     bool randomise = false,
     int maxCandidates = 6800,
   }) {
@@ -258,7 +259,7 @@ class CoinSelection {
     required BigInt feePerKb,
     required BigInt minFee,
     required BigInt minChange,
-    int locktime = 0,
+    Locktime locktime = Locktime.zero,
   }) => CoinSelection.inOrderUntilEnough(
     version: version,
     candidates: candidates.toList()..shuffle(),
@@ -281,7 +282,7 @@ class CoinSelection {
     required BigInt feePerKb,
     required BigInt minFee,
     required BigInt minChange,
-    int locktime = 0,
+    Locktime locktime = Locktime.zero,
   }) => CoinSelection.inOrderUntilEnough(
     version: version,
     candidates: candidates.toList().sorted(

coinlib/lib/src/tx/locktime.dart

@@ -0,0 +1,82 @@
+import 'package:coinlib/src/common/checks.dart';
+import 'inputs/sequence.dart';
+
+/// A locktime restricts when a transaction can be mined.
+///
+/// Either it is restricted to block heights that are equal or later than a
+/// given block height. For this use [BlockHeightLocktime].
+///
+/// Or it is restricted to where the median timestamp of the last 11 blocks is
+/// equal or later than a given timestamp. For this use [MedianTimeLocktime].
+///
+/// This restriction is ignored if all the transaction inputs are final with a
+/// [InputSequence.finalWithoutLocktime] sequence.
+sealed class Locktime {
+
+  static final int _timeThreshold = 500000000;
+
+  static const zero = BlockHeightLocktime._noCheck(0);
+
+  final int value;
+
+  const Locktime._noCheck(this.value);
+
+  Locktime._(this.value) {
+    checkUint32(value);
+  }
+
+  /// Creates a [BlockHeightLocktime] or [MedianTimeLocktime] from the raw
+  /// value.
+  factory Locktime(int value) {
+    if (value < _timeThreshold) return BlockHeightLocktime(value);
+    return MedianTimeLocktime._(value);
+  }
+
+  /// Given the [medianTime] of the previous 11 blocks and the current
+  /// [blockHeight], returns true if the locktime is reached and the transaction
+  /// is unlocked.
+  bool isUnlocked(DateTime medianTime, int blockHeight)
+    => this is BlockHeightLocktime
+    ? value <= blockHeight
+    : (this as MedianTimeLocktime).time.compareTo(medianTime) <= 0;
+
+}
+
+class BlockHeightLocktime extends Locktime {
+
+  const BlockHeightLocktime._noCheck(super.height) : super._noCheck();
+
+  /// Restricts the transaction to block heights greater or equal to [height].
+  ///
+  /// The [height] be less than 500000000.
+  BlockHeightLocktime(int height) : super._(height) {
+    if (height >= Locktime._timeThreshold) {
+      throw ArgumentError.value(
+        height, "height", "must be less than ${Locktime._timeThreshold}",
+      );
+    }
+  }
+
+}
+
+class MedianTimeLocktime extends Locktime {
+
+  MedianTimeLocktime._(int value) : super._(value) {
+    if (value < Locktime._timeThreshold) {
+      throw ArgumentError.value(
+        value, "value", "must be more or equal to ${Locktime._timeThreshold}",
+      );
+    }
+  }
+
+  /// Restricts the transaction to blocks where the median timestamp of the
+  /// previous 11 blocks is greater than or equal to [time].
+  ///
+  /// Must be between "1985-11-05 00:53:20" and "2106-02-07 06:28:15".
+  MedianTimeLocktime(
+    DateTime time,
+  ) : this._(time.millisecondsSinceEpoch ~/ 1000);
+
+  DateTime get time => DateTime.fromMillisecondsSinceEpoch(value*1000);
+
+}

coinlib/lib/src/tx/sighash/taproot_signature_hasher.dart

@@ -42,7 +42,7 @@ final class TaprootSignatureHasher extends SignatureHasher with Writable {
 
     // Total transaction data
     writer.writeUInt32(tx.version);
-    writer.writeUInt32(tx.locktime);
+    writer.writeUInt32(tx.locktime.value);
 
     if (hashType.allInputs) {
       writer.writeSlice(txHashes.prevouts.singleHash);

coinlib/lib/src/tx/sighash/witness_signature_hasher.dart

@@ -44,7 +44,7 @@ final class WitnessSignatureHasher extends SignatureHasher with Writable {
     writer.writeUInt64(details.value);
     writer.writeUInt32(thisInput.sequence.value);
     writer.writeSlice(hashOutputs);
-    writer.writeUInt32(tx.locktime);
+    writer.writeUInt32(tx.locktime.value);
     writer.writeUInt32(hashType.value);
 
   }

coinlib/lib/src/tx/transaction.dart

@@ -7,6 +7,7 @@ import 'package:coinlib/src/crypto/hash.dart';
 import 'package:coinlib/src/tx/inputs/sequence.dart';
 import 'package:coinlib/src/tx/inputs/taproot_key_input.dart';
 import 'package:coinlib/src/tx/inputs/taproot_single_script_sig_input.dart';
+import 'package:coinlib/src/tx/locktime.dart';
 import 'inputs/input.dart';
 import 'inputs/input_signature.dart';
 import 'inputs/legacy_input.dart';
@@ -45,22 +46,24 @@ class Transaction with Writable {
   final int version;
   final List<Input> inputs;
   final List<Output> outputs;
-  final int locktime;
+  final Locktime locktime;
 
   /// Constructs a transaction with the given [inputs] and [outputs].
   /// [TransactionTooLarge] will be thrown if the resulting transction exceeds
   /// [maxSize] (1MB).
+  ///
+  /// To follow the behaviour of the reference Peercoin client, the [locktime]
+  /// can be set to the current tip block height via [BlockHeightLocktime].
   Transaction({
     this.version = currentVersion,
     required Iterable<Input> inputs,
     required Iterable<Output> outputs,
-    this.locktime = 0,
+    this.locktime = Locktime.zero,
   })
   : inputs = List.unmodifiable(inputs),
   outputs = List.unmodifiable(outputs)
   {
     checkInt32(version);
-    checkUint32(locktime);
     if (size > maxSize) throw TransactionTooLarge();
   }
 
@@ -103,7 +106,7 @@ class Transaction with Writable {
       version: version,
       inputs: inputs,
       outputs: outputs,
-      locktime: locktime,
+      locktime: Locktime(locktime),
     );
 
   }
@@ -182,7 +185,7 @@ class Transaction with Writable {
       }
     }
 
-    writer.writeUInt32(locktime);
+    writer.writeUInt32(locktime.value);
 
   }
 
@@ -444,4 +447,15 @@ class Transaction with Writable {
     (input) => input.sequence.locktimeIsEnforced,
   );
 
+  /// Given the [medianTime] of the previous 11 blocks and the current
+  /// [blockHeight], returns true if the transaction is unlocked and available
+  /// for inclusion into a block.
+  ///
+  /// This returns true if [locktimeIsEnforced] is false and otherwise checks
+  /// the locktime.
+  bool isUnlocked({
+    required DateTime medianTime,
+    required int blockHeight,
+  }) => !locktimeIsEnforced || locktime.isUnlocked(medianTime, blockHeight);
+
 }

coinlib/test/tx/coin_selection_test.dart

@@ -171,7 +171,7 @@ void main() {
             vector.outputValue + vector.expChangeValue,
           );
           expect(tx.version, Transaction.currentVersion);
-          expect(tx.locktime, 0);
+          expect(tx.locktime.value, 0);
 
         } else {
           expect(
@@ -188,7 +188,7 @@ void main() {
 
       final selection = CoinSelection(
         version: 1234,
-        locktime: 54,
+        locktime: Locktime(54),
         selected: [candidateForValue(coin)],
         recipients: [outputForValue(10000)],
         changeProgram: changeProgram,
@@ -199,7 +199,7 @@ void main() {
 
       final tx = selection.transaction;
       expect(tx.version, 1234);
-      expect(tx.locktime, 54);
+      expect(tx.locktime.value, 54);
 
     });
 
@@ -278,7 +278,7 @@ void main() {
         unorderedEquals(values),
       );
       expect(selection.version, 1234);
-      expect(selection.locktime, 0xabcd1234);
+      expect(selection.locktime.value, 0xabcd1234);
     }
 
     final candidates = [coin*4, coin, coin*3, coin, coin*2];
@@ -292,7 +292,7 @@ void main() {
           recipients: [outputForValue(outValue)],
           changeProgram: changeProgram,
           feePerKb: feePerKb, minFee: minFee, minChange: minChange,
-          locktime: 0xabcd1234,
+          locktime: Locktime(0xabcd1234),
         );
         expectSelectedValues(selection, selected);
       }
@@ -316,7 +316,7 @@ void main() {
         recipients: [outputForValue(outValue)],
         changeProgram: changeProgram,
         feePerKb: feePerKb, minFee: minFee, minChange: minChange,
-        locktime: 0xabcd1234,
+        locktime: Locktime(0xabcd1234),
       );
 
       // Only need one
@@ -347,7 +347,7 @@ void main() {
           recipients: [outputForValue(outValue)],
           changeProgram: changeProgram,
           feePerKb: feePerKb, minFee: minFee, minChange: minChange,
-          locktime: 0xabcd1234,
+          locktime: Locktime(0xabcd1234),
         );
         expectSelectedValues(selection, selected);
       }
@@ -372,7 +372,7 @@ void main() {
           recipients: [outputForValue(outValue)],
           changeProgram: changeProgram,
           feePerKb: feePerKb, minFee: minFee, minChange: minChange,
-          locktime: 0xabcd1234,
+          locktime: Locktime(0xabcd1234),
         );
 
       // Defaults to random where possible
@@ -397,7 +397,7 @@ void main() {
         expect(selection.tooLarge, false);
         expect(selection.enoughFunds, true);
         expect(selection.version, 1234);
-        expect(selection.locktime, 0xabcd1234);
+        expect(selection.locktime.value, 0xabcd1234);
         expect(
           selection.selected.where(
             (candidate) => candidate.value.toInt() == coin*100,