> For the complete documentation index, see [llms.txt](https://radiantblockchain.gitbook.io/wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://radiantblockchain.gitbook.io/wiki/programming/scryptlib/chained-apis.md). # Chained APIs ## Using Chained APIs Chained APIs [简体中文版](/wiki/programming/scryptlib/chained-apis/chained-apis-chinese.md) When deploying and calling a contract, it is often necessary to calculate the transaction fee and the change output. Without knowing the size of the unlocking script, it is difficult to calculate both. **scryptlib** extends the [**bsv**](https://github.com/moneybutton/bsv) library and provides a set of chained APIs to simplify building transactions in these cases. ### Deploy Contract The following is a function that deploys any type of contracts. ```javascript async function deployContract(contract, amount) { const address = privateKey.toAddress() const tx = new bsv.Transaction() tx.from(await fetchUtxos(address)) // Add UTXOs/bitcoins that are locked into the contract and pay for miner fees. In practice, wallets only add enough UTXOs, not all UTXOs as done here for ease of exposition. .addOutput(new bsv.Transaction.Output({ script: contract.lockingScript, // Deploy the contract to the 0-th output satoshis: amount, })) .change(address) // Add change output .sign(privateKey) // Sign inputs. Only apply to P2PKH inputs. await sendTx(tx) // Broadcast transaction return tx } ``` ### Call contract There are two cases when calling a public function of a contract: 1. The function takes a parameter of type `SigHashPreimage` 2. No `SigHashPreimage` parameter. #### No `SigHashPreimage` If the public function of the contract being called does not contain parameter of type `SigHashPreimage`, it is relatively simple to build a transaction calling it. Generally, you can build a transaction according to the following steps: 1. Create an input from a previous transaction where the contract is located by `createInputFromPrevTx(tx, outputIndex)` and add it to the transaction. 2. Use `change(address)` to add a change output. 3. Use `setInputScript(inputIndex, (tx, output) => bsv.Script)` to set the unlocking script for the input added in step 1. 4. Call `seal()` to finalize the transaction, and automatically calculate the correct transaction fee and change balance. ```javascript const demo = new Demo(4, 7); const deployTx = await deployContract(demo, 1000); // Deploy a contract const unlockingTx = new bsv.Transaction(); unlockingTx.addInput(createInputFromPrevTx(deployTx)) .change(privateKey.toAddress()) .setInputScript(0, (_) => { // Set the unlocking script for 0-th input return demo.add(11).toScript(); }) .feePerKb(250) // Set transaction fee rate. Optional, default is 500 satoshis per KB .seal() // Finalize the transaction and automatically calculate the correct transaction fee and change amount // Broadcast transaction await sendTx(unlockingTx) ``` #### `SigHashPreimage` If the public function of the contract contains parameters of type `SigHashPreimage`, it is more complicated to build the transaction calling it. This is because unlocking script containing `SigHashPreimage` affects the calculation of transaction fee and thus the `satoshis` amount in the output. In turn, `satoshis` affects the calculation of `SigHashPreimage`. The chained APIs provided by **scryptlib** hides the details of processing these inter-dependent calculations. You only need to build the transaction in the following way: **1. Transaction fees paid by the bitcoins locked in the contract:** In this case, no separate change output is included. The balances of all outputs are unknown before the transaction is built. Transaction fees will affect the calculation of all output balances. 1. Create an input from the transaction where the contract is located by `createInputFromPrevTx(tx, outputIndex)` and add it to the transaction. 2. Use `setOutput(outputIndex, (tx) => bsv.Transaction.Output)` to add one or more outputs. The output balance usually needs to subtract transaction fee; `javascript const newAmount = amount - tx.getEstimateFee();` 3. Use `setInputScript(inputIndex, (tx, output) => bsv.Script)` to set the unlocking script for the input added in step 1. The unlocking parameter usually contains a parameter that specifies the new balance of the contract and its calculation is the same as the previous step. 4. Call `seal()` to finalize the transaction and automatically calculate the correct transaction fee and change amount. ```javascript const counter = new StateCounter(0) let amount = 8000 const lockingTx = await deployContract(counter, amount) // Deploy a contract const unlockingTx = new bsv.Transaction(); unlockingTx.addInput(createInputFromPrevTx(prevTx)) .setOutput(0, (tx) => { const newLockingScript = counter.getNewStateScript({ counter: i + 1 }) const newAmount = amount - tx.getEstimateFee(); // To calculate the new balance of the contract, you need to subtract the transaction fee return new bsv.Transaction.Output({ script: newLockingScript, satoshis: newAmount, }) }) .setInputScript(0, (tx, output) => { // output contains the locking script and satoshis balance of the UTXO const preimage = getPreimage(tx, output.script, output.satoshis) const newAmount = amount - tx.getEstimateFee(); // To calculate the new balance of the contract, you need to subtract the transaction fee return counter.unlock(new SigHashPreimage(toHex(preimage)), newAmount).toScript() }) .seal() // Finalize the transaction // Broadcast transaction await sendTx(unlockingTx) ``` **2. Transaction fees paid by adding other inputs:** In this case, a separate change output is included. The balance of other outputs can generally be calculated before the transaction is built. Transaction fees only affect the calculation of change output. 1. Create an input from the transaction where the contract is located by `createInputFromPrevTx(tx, outputIndex)` and add it to the transaction 2. Use `from([utxo])` to add inputs used to pay transaction fee. 3. Use `addOutput()` to add one or more outputs (add according to the contract business logic). 4. Use `change(address)` to add a change output. 5. Use `setInputScript(inputIndex, (tx, output) => bsv.Script)` to set the unlocking script for the input added in step 1. The unlocking parameters usually contains a parameter that specifies the change amount, which can be obtained through `tx.getChangeAmount()`. 6. Use `sign(privateKey)` to sign all inputs added to pay transaction fee. 7. Call `seal()` to finalize the transaction. ```javascript ... const unlockingTx = new bsv.Transaction(); const newAmount = amount + spendAmount； // The new balance of contract has nothing to do with transaction fee unlockingTx.addInput(createInputFromPrevTx(lockingTx)) .from(await fetchUtxos(privateKey.toAddress())) // Add inputs to pay transaction fees .addOutput(new bsv.Transaction.Output({ // Add one or more outputs, newAmount is the new balance of the contract script: newLockingScript, satoshis: newAmount, })) .change(privateKey.toAddress()) // Add change output .setInputScript(0, (tx, output) => { let preimage = getPreimage( tx, output.script, output.satoshis, 0, sighashType ); return advTokenSale.buy( new SigHashPreimage(toHex(preimage)), new Ripemd160(toHex(pkh)), // Change address tx.getChangeAmount(), // Calculate the change balance new Bytes(toHex(publicKeys[i])), numBought ).toScript(); }) .sign(privateKey) // Sign all inputs added to pay transaction fee .seal() // Finalize the transaction // Broadcast transaction lockingTxid = await sendTx(unlockingTx) ``` ### Extended APIs list | Api | description | parameters | | ------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setInputScript` | Set input unlocking script |

1. inputIndex Input index
2. (tx, output) => bsv.Script A callback function returns the unlocking script of the input

| | `setOutput` | Add output to the specified index |

1. outputIndex Output index
2. (tx) => bsv.Transaction.Output A callback function returns the output

| | `setLockTime` | Set the transaction's `nLockTime` | 1. `nLockTime` | | `setInputSequence` | Set the `sequenceNumber` |

1. inputIndex Input index
2. sequenceNumber

| | `seal` | Seal transactions. Transactions after sealing can no longer be modified | - | | `getChangeAmount` | Get the balance of the change output | - | | `getEstimateFee` | Estimate transaction fee based on transaction size and fee rate | - | | `checkFeeRate` | Check whether the transaction fee meets the fee rate | 1. `feePerKb` fee rate, satoshis per KB | | `prevouts` | returns the serialization of all input outpoints | - |