@smartledger/bsv 9.12.0 → 9.14.0

package/bsv.d.ts

@@ -987,6 +987,10 @@ declare module '@smartledger/bsv' {
          * The easiest target a header may declare and still be believed: difficulty 1,
          * 0x1d00ffff, the proof-of-work limit of mainnet and testnet. Regtest declares
          * 0x207fffff, so regtest headers need `powLimit` set explicitly.
+         *
+         * This rules out a FREE forgery, not a cheap one: a header at difficulty 1 costs
+         * about 4.3e9 double-SHA256 attempts, against about 1e20 for a real mainnet header.
+         * Use `minWork`, or check the header against your own chain source.
          */
         const POW_LIMIT_BITS: number;
         /** A Merkle branch proof. All hashes are DISPLAY-order hex; a node of '*' means "duplicate the working hash". */
@@ -1005,8 +1009,18 @@ declare module '@smartledger/bsv' {
              * declares its own target, so without this a forged header costs nothing to make.
              */
             powLimit?: number | string | object;
-            /** Minimum work the header must represent: 2^256 / (target + 1). Difficulty 1 is about 4.295e9. */
+            /**
+             * Minimum work the header must represent, in HASHES: 2^256 / (target + 1).
+             * Difficulty 1 is about 4.295e9. Use `minDifficulty` to say it in difficulty.
+             */
             minWork?: number | string | object;
+            /**
+             * The same floor in DIFFICULTY, which is the unit difficulty is quoted in: a real
+             * BSV header is about 2.6e10, i.e. about 1.1e20 hashes. Exactly one of the two —
+             * passing both throws, because they are 4.3e9 apart and silence would hide which
+             * one applied.
+             */
+            minDifficulty?: number | string;
         }
         interface InclusionResult {
             valid: boolean;
@@ -1723,6 +1737,11 @@ declare module '@smartledger/bsv' {
             /**
              * The block hash the caller's own chain source has at that height. No amount of
              * proof of work detects an orphan: a block that lost a race carries real work.
+             *
+             * Supplying this or `minWork` will be REQUIRED in 10.0.0: the proof-of-work limit
+             * rules out a free forgery, not a cheap one — a header at difficulty 1 costs about
+             * 4.3e9 hashes, while a real mainnet header carries about 1e20. Verifying with a
+             * header alone warns since 9.13.0.
              */
             blockHashAtHeight?: string;
             /**
@@ -1730,8 +1749,17 @@ declare module '@smartledger/bsv' {
              * SPV.POW_LIMIT_BITS (difficulty 1); regtest headers need 0x207fffff.
              */
             powLimit?: number | string;
-            /** Minimum work the header must represent. Difficulty 1 is about 4.295e9. */
+            /**
+             * Minimum work the header must represent, in HASHES. Difficulty 1 is about
+             * 4.295e9, and a real mainnet header carries about 1e20. Either this,
+             * `minDifficulty` or `blockHashAtHeight` will be required in 10.0.0.
+             */
             minWork?: number | string;
+            /**
+             * The same floor in DIFFICULTY (a real BSV header is about 2.6e10). Exactly one
+             * of this and `minWork`; passing both throws.
+             */
+            minDifficulty?: number | string;
             /** Pass false only for test fixtures. Defaults to true. */
             requirePow?: boolean;
         }