smartledger-bsv 3.1.0 → 3.2.0

package/docs/networks.md

@@ -0,0 +1,55 @@
+# Networks
+Bitcore provides support for the main bitcoin network as well as for `testnet3`, the current test blockchain. We encourage the use of `Networks.livenet` and `Networks.testnet` as constants. Note that the library sometimes may check for equality against this object. Please avoid creating a deep copy of this object.
+
+The `Network` namespace has a function, `get(...)` that returns an instance of a `Network` or `undefined`. The only argument to this function is some kind of identifier of the network: either its name, a reference to a Network object, or a number used as a magic constant to identify the network (for example, the value `0` that gives bitcoin addresses the distinctive `'1'` at its beginning on livenet, is a `0x6F` for testnet).
+
+## Regtest
+
+The regtest network is useful for development as it's possible to programmatically and instantly generate blocks for testing. It's currently supported as a variation of testnet. Here is an example of how to use regtest with the Bitcore Library:
+
+```javascript
+// Standard testnet
+> bsv.Networks.testnet.networkMagic;
+<Buffer 0b 11 09 07>
+```
+
+```javascript
+// Enabling testnet to use the regtest port and magicNumber
+> bsv.Networks.enableRegtest();
+> bsv.Networks.testnet.networkMagic;
+<Buffer fa bf b5 da>
+```
+
+## Setting the Default Network
+Most projects will only need to work with one of the networks. The value of `Networks.defaultNetwork` can be set to `Networks.testnet` if the project will need to only to work on testnet (the default is `Networks.livenet`).
+
+## Network constants
+The functionality of testnet and livenet is mostly similar (except for some relaxed block validation rules on testnet). They differ in the constants being used for human representation of base58 encoded strings. These are sometimes referred to as "version" constants.
+
+Take a look at this modified snippet from [networks.js](https://github.com/bitpay/bsv/blob/master/lib/networks.js)
+
+```javascript
+var livenet = new Network();
+_.extend(livenet, {
+  name: 'livenet',
+  alias: 'mainnet',
+  pubkeyhash: 0x00,
+  privatekey: 0x80,
+  scripthash: 0x05,
+  xpubkey:  0x0488b21e,
+  xprivkey: 0x0488ade4,
+  port: 8333
+});
+
+var testnet = new Network();
+_.extend(testnet, {
+  name: 'testnet',
+  alias: 'testnet',
+  pubkeyhash: 0x6f,
+  privatekey: 0xef,
+  scripthash: 0xc4,
+  xpubkey: 0x043587cf,
+  xprivkey: 0x04358394,
+  port: 18333
+});
+```

package/docs/preimage.md

@@ -0,0 +1,126 @@
+Excellent — here’s the **definitive, detailed breakdown** of a **Bitcoin (BSV) sighash preimage**, field by field, based on **BIP143** (which all modern BSV libraries, including SmartLedger’s hardened bundle, follow exactly).
+
+---
+
+# 🔍 **Bitcoin SV Sighash Preimage Structure (BIP143 / ForkID)**
+
+The *preimage* is the exact data that gets double-SHA256 hashed before signing a transaction input with `SIGHASH_FORKID`.
+This deterministic byte layout ensures signatures are reproducible and verifiable.
+
+---
+
+## 🧩 **Overview**
+
+| Section                       | Bytes        | Endianness          | Description                                |          |
+| ----------------------------- | ------------ | ------------------- | ------------------------------------------ | -------- |
+| **1. nVersion**               | 4            | Little-Endian (LE)  | Transaction version field                  |          |
+| **2. hashPrevouts**           | 32           |                     | SHA256d of all input outpoints             |          |
+| **3. hashSequence**           | 32           |                     | SHA256d of all input sequences             |          |
+| **4. outpoint (txid + vout)** | 36           | txid: LE, index: LE | The outpoint being signed                  |          |
+| **5. scriptCode length**      | 1–3 (varint) |                     | Compact size of the script being signed    |          |
+| **6. scriptCode**             | variable     |                     | The actual script (usually `scriptPubKey`) |          |
+| **7. amount**                 | 8            | Little-Endian       | Value of the output being spent            |          |
+| **8. nSequence**              | 4            | Little-Endian       | Sequence number of this input              |          |
+| **9. hashOutputs**            | 32           |                     | SHA256d of all outputs                     |          |
+| **10. nLockTime**             | 4            | Little-Endian       | Locktime for entire tx                     |          |
+| **11. sighashType**           | 4            | Little-Endian       | SIGHASH type used (e.g., `0x41` for `ALL   | FORKID`) |
+
+---
+
+## 📏 **Typical Length Example**
+
+For a *simple single-input, single-output* transaction:
+
+| Section                 | Typical Bytes | Example Hex Segment      |
+| ----------------------- | ------------- | ------------------------ |
+| nVersion                | 4             | `01000000`               |
+| hashPrevouts            | 32            | `e3...4a`                |
+| hashSequence            | 32            | `00...00`                |
+| outpoint                | 36            | `00..00 00000000`        |
+| scriptCode (len + data) | 25            | `1976a914...88ac`        |
+| amount                  | 8             | `1027000000000000`       |
+| nSequence               | 4             | `ffffffff`               |
+| hashOutputs             | 32            | `d2...1e`                |
+| nLockTime               | 4             | `e8030000` *(= 1000 LE)* |
+| sighashType             | 4             | `41000000` *(= 0x41)*    |
+
+---
+
+### 🧮 **Total: ~108 bytes**
+
+(4 + 32 + 32 + 36 + 25 + 8 + 4 + 32 + 4 + 4 = 181, but since script length and varints can vary,
+the final preimage for a minimal transaction typically is **~108 bytes**.)
+
+---
+
+## 🧠 **Endianness Notes**
+
+* **nVersion, amount, nSequence, nLockTime, sighashType** are *little-endian* integers.
+* **hashPrevouts, hashSequence, hashOutputs** are *big-endian* SHA256d hashes (32 bytes each).
+* **txid** inside the *outpoint* is *little-endian* (it’s reversed from what’s printed on explorers).
+
+---
+
+## 🧩 **Visual Layout Example**
+
+```
+[0000-0003] nVersion (4 LE)
+[0004-0023] hashPrevouts (32)
+[0024-0043] hashSequence (32)
+[0044-005f] outpoint.txid (32 LE)
+[0060-0063] outpoint.vout (4 LE)
+[0064-007e] script length + scriptPubKey (varies)
+[007f-0086] amount (8 LE)
+[0087-008a] nSequence (4 LE)
+[008b-00aa] hashOutputs (32)
+[00ab-00ae] nLockTime (4 LE)
+[00af-00b2] sighashType (4 LE)
+```
+
+---
+
+## ⚙️ **In Script Context (OP_SPLIT / Covenant Use)**
+
+If you push the **raw preimage** onto the stack, you can target sections as follows:
+
+| Target           | Extraction Logic                             | Example ASM                                             |
+| ---------------- | -------------------------------------------- | ------------------------------------------------------- |
+| **nVersion**     | First 4 bytes                                | `4 OP_SPLIT OP_DROP OP_BIN2NUM`                         |
+| **nLockTime**    | 8 bytes from end → drop last 4 (sighashType) | `<len-8> OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
+| **hashPrevouts** | 32 bytes after first 4                       | `4 OP_SPLIT OP_DROP 32 OP_SPLIT OP_DROP`                |
+| **hashOutputs**  | 8+4+32 from end (44 bytes from tail)         | `<len-44> OP_SPLIT OP_NIP 32 OP_SPLIT OP_DROP`          |
+
+---
+
+## 🧾 **Checksum Behavior**
+
+The `sighashPreimage` is *never hashed directly* into the blockchain.
+Instead:
+
+```
+signature = ECDSA.sign( sha256sha256(preimage), privKey )
+```
+
+In your covenant scripts, you typically:
+
+1. Re-hash the preimage (`OP_HASH256`) to verify it matches what was signed.
+2. Then you may dissect it to verify constraints (like `nLockTime`, `nVersion`, etc.).
+
+---
+
+## ✅ **Summary Table**
+
+| Field        | Bytes    | Endian | Covenant Extraction Example                             |
+| ------------ | -------- | ------ | ------------------------------------------------------- |
+| nVersion     | 4        | LE     | `4 OP_SPLIT OP_DROP OP_BIN2NUM`                         |
+| hashPrevouts | 32       | —      | `36 OP_SPLIT ...`                                       |
+| hashSequence | 32       | —      | next 32                                                 |
+| outpoint     | 36       | mixed  | —                                                       |
+| scriptCode   | variable | —      | rarely enforced directly                                |
+| amount       | 8        | LE     | `40 OP_SPLIT OP_NIP 8 OP_SPLIT OP_DROP OP_BIN2NUM`      |
+| nSequence    | 4        | LE     | `12 OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM`      |
+| hashOutputs  | 32       | —      | —                                                       |
+| nLockTime    | 4        | LE     | `<len-8> OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
+| sighashType  | 4        | LE     | `<len-4> OP_SPLIT OP_NIP OP_BIN2NUM`                    |
+
+---

package/docs/script.md

@@ -0,0 +1,139 @@
+# Script
+All bitcoin transactions have scripts embedded into its inputs and outputs.  The scripts use a very simple programming language, which is evaluated from left to right using a stack. The language is designed such that it guarantees all scripts will execute in a limited amount of time (it is Turing-Complete).
+
+When a transaction is validated, the input scripts are concatenated with the output scripts and evaluated. To be valid, all transaction scripts must evaluate to true.  A good analogy for how this works is that the output scripts are puzzles that specify in which conditions can those bitcoins be spent. The input scripts provide the correct data to make those output scripts evaluate to true.
+
+For more detailed information about the bitcoin scripting language, check the online reference [on bitcoin's wiki](https://en.bitcoin.it/wiki/Script).
+
+The `Script` object provides an interface to construct, parse, and identify bitcoin scripts. It also gives simple interfaces to create most common script types. This class is useful if you want to create custom input or output scripts. In other case, you should probably use `Transaction`.
+
+## Script creation
+Here's how to use `Script` to create the five most common script types:
+
+### Pay to Public Key Hash (p2pkh)
+This is the most commonly used transaction output script. It's used to pay to a bitcoin address (a bitcoin address is a public key hash encoded in base58check)
+
+```javascript
+// create a new p2pkh paying to a specific address
+var address = Address.fromString('1NaTVwXDDUJaXDQajoa9MqHhz4uTxtgK14');
+var script = Script.buildPublicKeyHashOut(address);
+assert(script.toString() === 'OP_DUP OP_HASH160 20 0xecae7d092947b7ee4998e254aa48900d26d2ce1d OP_EQUALVERIFY OP_CHECKSIG');
+```
+
+### Pay to Public Key (p2pk)
+Pay to public key scripts are a simplified form of the p2pkh, but aren't commonly used in new transactions anymore, because p2pkh scripts are more secure (the public key is not revealed until the output is spent).
+
+```javascript
+// create a new p2pk paying to a specific public key
+var pubkey = new PublicKey('022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da');
+var script = Script.buildPublicKeyOut(pubkey);
+assert(script.toString() === '33 0x022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da OP_CHECKSIG');
+```
+
+### Pay to Multisig (p2ms)
+Multisig outputs allow to share control of bitcoins between several keys. When creating the script, one specifies the public keys that control the funds, and how many of those keys are required to sign off spending transactions to be valid. An output with N public keys of which M are required is called an m-of-n output (For example, 2-of-3, 3-of-5, 4-of-4, etc.)
+
+Note that regular multisig outputs are rarely used nowadays. 
+
+```javascript
+// create a new 2-of-3 multisig output from 3 given public keys
+var pubkeys = [
+  new PublicKey('022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da'),
+  new PublicKey('03e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e9'),
+  new PublicKey('021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc18'),
+];
+var threshold = 2;
+var script = Script.buildMultisigOut(pubkeys, threshold);
+assert(script.toString() === 'OP_2 33 0x022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da'
+      + ' 33 0x03e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e9'
+      + ' 33 0x021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc18 OP_3 OP_CHECKMULTISIG');
+```
+
+### Pay to Script Hash (p2sh)
+
+DEPRECATED - Do not use p2sh on Bitcoin SV.
+
+Pay to script hash outputs are scripts that contain the hash of another script, called `redeemScript`. To spend bitcoins sent in a p2sh output, the spending transaction must provide a script matching the script hash and data which makes the script evaluate to true.  This allows to defer revealing the spending conditions to the moment of spending. It also makes it possible for the receiver to set the conditions to spend those bitcoins.
+
+Most multisig transactions today use p2sh outputs where the `redeemScript` is a multisig output.
+
+```javascript
+// create a p2sh multisig output
+var pubkeys = [
+  new PublicKey('022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da'),
+  new PublicKey('03e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e9'),
+  new PublicKey('021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc18'),
+];
+var redeemScript = Script.buildMultisigOut(pubkeys, 2);
+var script = redeemScript.toScriptHashOut();
+assert(script.toString() === 'OP_HASH160 20 0x620a6eeaf538ec9eb89b6ae83f2ed8ef98566a03 OP_EQUAL');
+```
+
+### Data output
+Data outputs are used to push data into the blockchain. Up to 40 bytes can be pushed in a standard way, but more data can be used, if a miner decides to accept the transaction.
+
+```javascript
+var data = 'hello world!!!';
+var script = Script.buildDataOut(data);
+assert(script.toString() === 'OP_RETURN 14 0x68656c6c6f20776f726c64212121'
+```
+
+### Custom Scripts
+To create a custom `Script` instance, you must rely on the lower-level methods `add` and `prepend`. Both methods accept the same parameter types, and insert an opcode or data at the beginning (`prepend`) or end (`add`) of the `Script`.
+
+```
+var script = Script()
+  .add('OP_IF')                       // add an opcode by name
+  .prepend(114)                       // add OP_2SWAP by code
+  .add(Opcode.OP_NOT)                 // add an opcode object
+  .add(Buffer.from('bacacafe', 'hex')) // add a data buffer (will append the size of the push operation first)
+
+assert(script.toString() === 'OP_2SWAP OP_IF OP_NOT 4 0xbacacafe');
+```
+
+## Script Parsing and Identification
+`Script` has an easy interface to parse raw scripts from the network or bitcoind, and to extract useful information. An illustrative example (for more options check the API reference)
+
+```javascript
+var raw_script = Buffer.from('5221022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da2103e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e921021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc1853ae', 'hex');
+var s = new Script(raw_script);
+console.log(s.toString());
+// 'OP_2 33 0x022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da 33 0x03e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e9 33 0x021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc18 OP_3 OP_CHECKMULTISIG'
+
+s.isPublicKeyHashOut() // false
+s.isScriptHashOut() // false
+s.isMultisigOut() // true
+```
+
+## Script Interpreting and Validation
+To validate a transaction, the bitcoin network validates all of its inputs and outputs. To validate an input, the input's script is concatenated with the referenced output script, and the result is executed. If at the end of execution the stack contains a 'true' value, then the transaction is valid. You can do this in `bsv` by using the `Interpreter` class. The entry point (and probably the only interface you'll need for most applications) is the method `Interpreter#verify()`.
+
+You can use it like this:
+
+```javascript
+var inputScript = Script('OP_1');
+var outputScript = Script('OP_15 OP_ADD OP_16 OP_EQUAL');
+
+var verified = Interpreter().verify(inputScript, outputScript);
+// verified will be true
+```
+
+Note that `verify` expects two scripts: one is the input script (scriptSig) and the other is the output script (scriptPubkey). This is because different conditions are checked for each.
+
+It also accepts some optional parameters, assuming defaults if not provided:
+
+```javascript
+// first we create a transaction
+var tx = new Transaction()
+  .from(utxo)
+  .to(toAddress, 100000)
+  .sign(privateKey);
+
+// we then extract the signature from the first input
+var inputIndex = 0;
+var signature = tx.getSignatures(privateKey)[inputIndex].signature;
+
+var scriptSig = Script.buildPublicKeyHashIn(publicKey, signature);
+var flags = Interpreter.SCRIPT_VERIFY_P2SH | Interpreter.SCRIPT_VERIFY_STRICTENC;
+var verified = Interpreter().verify(scriptSig, scriptPubkey, tx, inputIndex, flags);
+```

package/docs/transaction.md

@@ -0,0 +1,174 @@
+# Transaction
+Bitcore provides a very simple API for creating transactions. We expect this API to be accessible for developers without knowing the working internals of bitcoin in deep detail. What follows is a small introduction to transactions with some basic knowledge required to use this API.
+
+A Transaction contains a set of inputs and a set of outputs. Each input contains a reference to another transaction's output, and a signature that allows the value referenced in that output to be used in this transaction.
+
+Note also that an output can be used only once. That's why there's a concept of "change address" in the bitcoin ecosystem: if an output of 10 BSV is available for me to spend, but I only need to transmit 1 BSV, I'll create a transaction with two outputs, one with 1 BSV that I want to spend, and the other with 9 BSV to a change address, so I can spend this 9 BSV with another private key that I own.
+
+So, in order to transmit a valid transaction, you must know what other transactions on the network store outputs that have not been spent and that are available for you to spend (meaning that you have the set of keys that can validate you own those funds). The unspent outputs are usually referred to as "utxo"s.
+
+Let's take a look at some very simple transactions:
+
+```javascript
+var transaction = new Transaction()
+    .from(utxos)          // Feed information about what unspent outputs one can use
+    .to(address, amount)  // Add an output with the given amount of satoshis
+    .change(address)      // Sets up a change address where the rest of the funds will go
+    .sign(privkeySet)     // Signs all the inputs it can
+```
+
+You can obtain the input and output total amounts of the transaction in satoshis by accessing the fields `inputAmount` and `outputAmount`.
+
+Now, this could just be serialized to hexadecimal ASCII values (`transaction.serialize()`) and sent over to the bitcoind reference client.
+
+```bash
+bitcoin-cli sendrawtransaction <serialized transaction>
+```
+
+You can also override the fee estimation with another amount, specified in satoshis:
+
+```javascript
+var transaction = new Transaction().fee(546); // Minimum non-dust amount
+var transaction = new Transaction().fee(1e8);  // Generous fee of 1 BSV
+```
+
+## Multisig Transactions
+To send a transaction to a multisig address, the API is the same as in the above example. To spend outputs that require multiple signatures, the process needs extra information: the public keys of the signers that can unlock that output.
+
+```javascript
+var multiSigTx = new Transaction()
+    .from(utxo, publicKeys, threshold)
+    .change(address)
+    .sign(myKeys);
+
+var serialized = multiSigTx.toObject();
+```
+
+This can be serialized and sent to another party, to complete with the needed signatures:
+
+```javascript
+var multiSigTx = new Transaction(serialized)
+    .sign(anotherSetOfKeys);
+
+assert(multiSigTx.isFullySigned());
+```
+
+Also, you can just send over the signature for your private key:
+
+```javascript
+var multiSigTx = new Transaction()
+    .from(utxo, publicKeys, threshold)
+    .change(address);
+
+var signature = multiSigTx.getSignatures(privateKey)[0];
+console.log(JSON.stringify(signature));
+console.log(signature.toObject());
+console.log(signature.signature.toString()); // Outputs a DER signature
+console.log(signature.sigtype);
+```
+
+Transfer that over the wire, and on the other side, apply it to a transaction:
+
+```javascript
+assert(transaction.isValidSignature(receivedSig));
+transaction.applySignature(receivedSig);
+```
+
+## Adding inputs
+Transaction inputs are instances of either [Input](https://github.com/bitpay/bsv/tree/master/lib/transaction/input) or its subclasses. `Input` has some abstract methods, as there is no actual concept of a "signed input" in the bitcoin scripting system (just valid signatures for <tt>OP_CHECKSIG</tt> and similar opcodes). They are stored in the `input` property of `Transaction` instances.
+
+Bitcore contains two implementations of `Input`, one for spending _Pay to Public Key Hash_ outputs (called `PublicKeyHashInput`) and another to spend _Pay to Script Hash_ outputs for which the redeem script is a Multisig script (called `MultisigScriptHashInput`).
+
+All inputs have the following five properties:
+- `prevTxId`: a `Buffer` with the id of the transaction with the output this input is spending
+- `outputIndex`: a `number` the index of the output in the previous transaction
+- `sequenceNumber`: a `number`, the sequence number, see [bitcoin's developer guide on nLockTime and the sequence number](https://bitcoin.org/en/developer-guide#locktime-and-sequence-number).
+- `script`: the `Script` instance for this input. Usually called `scriptSig` in the bitcoin community.
+- `output`: if available, a `Output` instance of the output associated with this input.
+
+Both `PublicKeyHashInput` and `MultisigScriptHashInput` cache the information about signatures, even though this information could somehow be encoded in the script. Both need to have the `output` property set in order to calculate the `sighash` so signatures can be created.
+
+Some methods related to adding inputs are:
+- `from`: A high level interface to add an input from a UTXO. It has a series of variants:
+  - `from(utxo)`: add an input from an [Unspent Transaction Output](http://bsv.io/guide/unspentoutput.html). Currently, only P2PKH outputs are supported.
+  - `from(utxos)`: same as above, but passing in an array of Unspent Outputs.
+  - `from(utxo, publicKeys, threshold)`: add an input that spends a UTXO with a P2SH output for a Multisig script. The `publicKeys` argument is an array of public keys, and `threshold` is the number of required signatures in the Multisig script.
+
+- `addInput`: Performs a series of checks on an input and appends it to the end of the `input` vector and updates the amount of incoming bitcoins of the transaction.
+- `uncheckedAddInput`: adds an input to the end of the `input` vector and updates the `inputAmount` without performing any checks.
+
+### PublicKeyHashInput
+This input uses the `script` property to mark the input as unsigned if the script is empty.
+
+### MultisigScriptHashInput
+This input contains a set of signatures in a `signatures` property, and each time a signature is added, a potentially partial and/or invalid script is created. The `isFullySigned` method will only return true if all needed signatures are already added and valid. If `addSignature` is added after all need signatures are already set, an exception will be thrown.
+
+## Signing a Transaction
+The following methods are used to manage signatures for a transaction:
+- `getSignatures`: takes an array of `PrivateKey` or strings from which a `PrivateKey` can be instantiated; the transaction to be signed; the kind of [signature hash to use](https://bitcoin.org/en/developer-guide#signature-hash-types). Returns an array of objects with the following properties:
+  - `signature`: an instance of [Signature](https://github.com/bitpay/bsv/blob/master/lib/crypto/signature.js)
+  - `prevTxId`: this input's `prevTxId`,
+  - `outputIndex`: this input's `outputIndex`,
+  - `inputIndex`: this input's index in the transaction
+  - `sigtype`: the "sighash", the type of transaction hash used to calculate the signature
+  - `publicKey`: a `PublicKey` of the `PrivateKey` used to create the signature
+
+- `addSignature`: takes an element outputed by `getSignatures` and applies the signature to this input (modifies the script to include the new signature).
+- `clearSignatures`: removes all signatures for this input
+- `isFullySigned`: returns true if the input is fully signed
+
+## Handling Outputs
+Outputs can be added by:
+- The `addOutput(output)` method, which pushes an `Output` to the end of the `outputs` property and updates the `outputAmount` field. It also clears signatures (as the hash of the transaction may have changed) and updates the change output.
+- The `to(address, amount)` method, that adds an output with the script that corresponds to the given address. Builds an output and calls the `addOutput` method.
+- Specifying a [change address](#Fee_calculation)
+
+To remove all outputs, you can use `clearOutputs()`, which preserves change output configuration.
+
+## Serialization
+There are a series of methods used for serialization:
+- `toObject`: Returns a plain JavaScript object with no methods and enough information to fully restore the state of this transaction. Using other serialization methods (except for `toJSON`) will cause a some information to be lost.
+- `toJSON`: Will be called when using `JSON.stringify` to return JSON-encoded string using the output from `toObject`.
+- `toString` or `uncheckedSerialize`: Returns an hexadecimal serialization of the transaction, in the [serialization format for bitcoin](https://bitcoin.org/en/developer-reference#raw-transaction-format).
+- `serialize`: Does a series of checks before serializing the transaction
+- `inspect`: Returns a string with some information about the transaction (currently a string formatted as `<Transaction 000...000>`, that only shows the serialized value of the transaction.
+- `toBuffer`: Serializes the transaction for sending over the wire in the bitcoin network
+- `toBufferWriter`: Uses an already existing BufferWriter to copy over the serialized transaction
+
+## Serialization Checks
+When serializing, the bsv library performs a series of checks. These can be disabled by providing an object to the `serialize` method with the checks that you'll like to skip.
+- `disableLargeFees` avoids checking that the fee is no more than `Transaction.FEE_PER_KB * Transaction.FEE_SECURITY_MARGIN * size_in_kb`.
+- `disableSmallFees` avoids checking that the fee is less than `Transaction.FEE_PER_KB * size_in_kb / Transaction.FEE_SECURITY_MARGIN`.
+- `disableIsFullySigned` does not check if all inputs are fully signed
+- `disableDustOutputs` does not check for dust outputs being generated
+- `disableMoreOutputThanInput` avoids checking that the sum of the output amounts is less than or equal to the sum of the amounts for the outputs being spent in the transaction
+
+These are the current default values in the bsv library involved on these checks:
+- `Transaction.FEE_PER_KB`: `10000` (satoshis per kilobyte)
+- `Transaction.FEE_SECURITY_MARGIN`: `15`
+- `Transaction.DUST_AMOUNT`: `546` (satoshis)
+
+## Fee calculation
+When outputs' value don't sum up to the same amount that inputs, the difference in bitcoins goes to the miner of the block that includes this transaction. The concept of a "change address" usually is associated with this: an output with an address that can be spent by the creator of the transaction.
+
+For this reason, some methods in the Transaction class are provided:
+- `change(address)`: Set up the change address. This will set an internal `_changeScript` property that will store the change script associated with that address.
+- `fee(amount)`: Sets up the exact amount of fee to pay. If no change address is provided, this will raise an exception.
+- `getFee()`: returns the estimated fee amount to be paid, based on the size of the transaction, but disregarding the priority of the outputs.
+
+Internally, a `_changeIndex` property stores the index of the change output (so it can get updated when a new input or output is added).
+
+## Time-Locking transaction
+All bitcoin transactions contain a locktime field. The locktime indicates the earliest time a transaction can be added to the blockchain. Locktime allows signers to create time-locked transactions which will only become valid in the future, giving the signers a chance to change their minds. Locktime can be set in the form of a bitcoin block height (the transaction can only be included in a block with a higher height than specified) or a linux timestamp (transaction can only be confirmed after that time). For more information see [bitcoin's development guide section on locktime](https://bitcoin.org/en/developer-guide#locktime-and-sequence-number).
+
+In bsv, you can set a `Transaction`'s locktime by using the methods `Transaction#lockUntilDate` and `Transaction#lockUntilBlockHeight`. You can also get a friendly version of the locktime field via `Transaction#getLockTime`;
+
+For example:
+
+```javascript
+var future = new Date(2025,10,30); // Sun Nov 30 2025
+var transaction = new Transaction()
+  .lockUntilDate(future);
+console.log(transaction.getLockTime());
+// output similar to: Sun Nov 30 2025 00:00:00 GMT-0300 (ART)
+```

package/docs/unspentoutput.md

@@ -0,0 +1,32 @@
+# UnspentOutput
+`bsv.Transaction.UnspentOutput` is a class with stateless instances that provides information about an unspent output:
+- Transaction ID and output index
+- The "scriptPubKey", the script included in the output
+- Amount of satoshis associated
+- Address, if available
+
+## Parameters
+The constructor is quite permissive with the input arguments. It can take outputs straight out of bitcoind's getunspent RPC call. Some of the names are not very informative for new users, so the UnspentOutput constructor also understands these aliases:
+- `scriptPubKey`: just `script` is also accepted
+- `amount`: expected value in BSV. If the `satoshis` alias is used, make sure to use satoshis instead of BSV.
+- `vout`: this is the index of the output in the transaction, renamed to `outputIndex`
+- `txid`: `txId`
+
+## Example
+
+```javascript
+var utxo = new UnspentOutput({
+  "txid" : "a0a08e397203df68392ee95b3f08b0b3b3e2401410a38d46ae0874f74846f2e9",
+  "vout" : 0,
+  "address" : "mgJT8iegL4f9NCgQFeFyfvnSw1Yj4M5Woi",
+  "scriptPubKey" : "76a914089acaba6af8b2b4fb4bed3b747ab1e4e60b496588ac",
+  "amount" : 0.00070000
+});
+var utxo = new UnspentOutput({
+  "txId" : "a0a08e397203df68392ee95b3f08b0b3b3e2401410a38d46ae0874f74846f2e9",
+  "outputIndex" : 0,
+  "address" : "mgJT8iegL4f9NCgQFeFyfvnSw1Yj4M5Woi",
+  "script" : "76a914089acaba6af8b2b4fb4bed3b747ab1e4e60b496588ac",
+  "satoshis" : 70000
+});
+```