Upload 34 files

auction.md

@@ -0,0 +1,296 @@
+---
+sidebar_position: 2
+---
+
+# Tutorial 2: Auction
+
+## Overview
+
+In this tutorial, we will go over how to build an auction contract. It is open and transparent, where everyone can participate and the highest bidder wins when the bidding is over.
+
+There are two ways to interact with the contract:
+
+1. Bid: if a higher bid is found, the current highest bidder is updated, and the previous highest bidder is refunded.
+2. Close: the auctioneer can close the auction after it expires and take the offer.
+
+## Contract Properties
+
+According to the interactions above, this contract needs to store three properties:
+
+- The auctioneer, who starts the auction
+- The deadline for the auction
+- The highest bidder until now
+
+```ts
+// The bidder's public key.
+@prop(true)
+bidder: PubKey
+
+// The auctioneer's public key.
+@prop()
+readonly auctioneer: PubKey
+
+// Deadline of the auction. Can be block height or timestamp.
+@prop()
+readonly auctionDeadline: bigint
+```
+
+## Constructor
+
+Initialize all the `@prop` properties in the constructor. Note that we don't need to pass a `bidder` parameter.
+
+```ts
+constructor(auctioneer: PubKey, auctionDeadline: bigint) {
+    super(...arguments)
+    // the initial bidder is the auctioneer himeself
+    this.bidder = auctioneer
+    this.auctioneer = auctioneer
+    this.auctionDeadline = auctionDeadline
+}
+```
+
+When deploying the contract, the auctioneer locked the minimal bid into the contract, and at this time, the highest bidder would be himself.
+
+```ts
+const auction = new Auction(publicKeyAuctioneer, auctionDeadline)
+const deployTx = await auction.deploy(minBid)
+```
+
+## Public Methods
+
+### Bid
+
+In method `public bid(bidder: PubKeyHash, bid: bigint)`, we need to check if the bidder has a higher bid than the previous one. If so, we update the highest bidder in the contract state and refund the previous bidder.
+
+We can read the previous highest bid from the balance of the contract UTXO.
+
+```ts
+const highestBid: bigint = this.ctx.utxo.value
+```
+
+Then it's easy to demand a higher bid.
+
+```ts
+assert(bid > highestBid, 'the auction bid is lower than the current highest bid')
+```
+
+The spending/redeeming tx has these outputs.
+
+![](https://lucid.app/publicSegments/view/bfe65136-2acd-4a46-ba63-a6ec4b6d7d4a/image.png)
+
+- Contract's new state output: records the new bidder and locks the new bid into contract UTXO.
+
+```ts
+// Log the previous highest bidder
+const highestBidder: PubKey = this.bidder
+// Change the public key of the highest bidder.
+this.bidder = bidder
+
+// Auction continues with a higher bidder.
+const auctionOutput: ByteString = this.buildStateOutput(bid)
+```
+
+- A refund P2PKH output: pay back the previous bidder.
+
+```ts
+// Refund previous highest bidder.
+const refundOutput: ByteString = Utils.buildPublicKeyHashOutput(highestBidder, highestBid)
+```
+
+- An optional change P2PKH output.
+
+```ts
+let outputs: ByteString = auctionOutput + refundOutput
+// Add change output.
+outputs += this.buildChangeOutput()
+```
+
+At last, we require the transaction to have these outputs using `ScriptContext`.
+
+```ts
+assert(hash256(outputs) == this.ctx.hashOutputs, 'hashOutputs check failed')
+```
+
+As `bid` is called continuously, the state of the contract is constantly updated. The highest bidder, and the highest bid as well, is recorded in the latest contract UTXO until the auctioneer closes the auction.
+
+```ts
+// Call this public method to bid with a higher offer.
+@method()
+public bid(bidder: PubKeyHash, bid: bigint) {
+    const highestBid: bigint = this.ctx.utxo.value
+    assert(bid > highestBid, 'the auction bid is lower than the current highest bid')
+
+    // Change the public key of the highest bidder.
+    const highestBidder: PubKey = this.bidder
+    this.bidder = bidder
+
+    // Auction continues with a higher bidder.
+    const auctionOutput: ByteString = this.buildStateOutput(bid)
+
+    // Refund previous highest bidder.
+    const refundOutput: ByteString = Utils.buildPublicKeyHashOutput(highestBidder, highestBid)
+
+    let outputs: ByteString = auctionOutput + refundOutput
+    // Add change output.
+    outputs += this.buildChangeOutput()
+
+    assert(hash256(outputs) == this.ctx.hashOutputs, 'hashOutputs check failed')
+}
+```
+
+### Close
+
+![](https://lucid.app/publicSegments/view/0f40689c-9727-423e-81ed-0d5df338dece/image.png)
+
+Method `public close(sig: Sig)` is simple, we require:
+
+- It can only be called by the auctioneer. That is why we need to pass in the caller's signature.
+
+```ts
+// Check signature of the auctioneer.
+assert(this.checkSig(sig, this.auctioneer), 'signature check failed')
+```
+
+- Now the auction deadline has passed
+
+```ts
+assert(this.ctx.locktime >= this.auctionDeadline, 'auction is not over yet')
+```
+
+:::note
+We don't place any constraint on transaction outputs here, because the auctioneer can send the highest bid to any address he controls, which is what we actually want.
+:::
+
+```ts
+// Close the auction if deadline is reached.
+@method()
+public close(sig: Sig) {
+    // Check deadline
+    assert(this.ctx.locktime >= this.auctionDeadline, 'auction is not over yet')
+    // Check signature of the auctioneer.
+    assert(this.checkSig(sig, this.auctioneer), 'signature check failed')
+}
+```
+
+## Customize tx builder for `bid`
+
+Using [default tx builder](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md#default-1) cannot meet our demand when calling `bid`, since the second output - the refund P2PKH output - is not a new contract instance.
+
+In Function `static bidTxBuilder(options: MethodCallOptions<Auction>, bidder: PubKeyHash, bid: bigint): Promise<ContractTransaction>`, we add all three outputs as designed.
+
+```ts
+const unsignedTx: Transaction = new Transaction()
+    // add contract input
+    .addInput(current.buildContractInput(options.fromUTXO))
+    // build next instance output
+    .addOutput(new Transaction.Output({script: nextInstance.lockingScript, satoshis: Number(bid),}))
+    // build refund output
+    .addOutput(
+        new Transaction.Output({
+            script: Script.fromHex(Utils.buildPublicKeyHashScript(current.bidder)),
+            satoshis: options.fromUTXO?.satoshis ?? current.from.tx.outputs[current.from.outputIndex].satoshis,
+        })
+    )
+    // build change output
+    .change(options.changeAddress)
+```
+
+## Conclusion
+
+Congratulations, you have completed the `Auction` contract!
+
+The [final complete code](https://github.com/sCrypt-Inc/boilerplate/blob/master/src/contracts/auction.ts) is as follows:
+
+```ts
+export class Auction extends SmartContract {
+    static readonly LOCKTIME_BLOCK_HEIGHT_MARKER = 500000000
+    static readonly UINT_MAX = 0xffffffffn
+
+    // The bidder's public key.
+    @prop(true)
+    bidder: PubKey
+
+    // The auctioneer's public key.
+    @prop()
+    readonly auctioneer: PubKey
+
+    // Deadline of the auction. Can be block height or timestamp.
+    @prop()
+    readonly auctionDeadline: bigint
+
+    constructor(auctioneer: PubKey, auctionDeadline: bigint) {
+        super(...arguments)
+        this.bidder = auctioneer
+        this.auctioneer = auctioneer
+        this.auctionDeadline = auctionDeadline
+    }
+
+    // Call this public method to bid with a higher offer.
+    @method()
+    public bid(bidder: PubKey, bid: bigint) {
+        const highestBid: bigint = this.ctx.utxo.value
+        assert(bid > highestBid, 'the auction bid is lower than the current highest bid')
+
+        // Change the public key of the highest bidder.
+        const highestBidder: PubKey = this.bidder
+        this.bidder = bidder
+
+        // Auction continues with a higher bidder.
+        const auctionOutput: ByteString = this.buildStateOutput(bid)
+
+        // Refund previous highest bidder.
+        const refundOutput: ByteString = Utils.buildPublicKeyHashOutput(hash160(highestBidder), highestBid)
+        let outputs: ByteString = auctionOutput + refundOutput
+
+        // Add change output.
+        outputs += this.buildChangeOutput()
+
+        assert(hash256(outputs) == this.ctx.hashOutputs, 'hashOutputs check failed')
+    }
+
+    // Close the auction if deadline is reached.
+    @method()
+    public close(sig: Sig) {
+        // Check deadline
+        assert(this.ctx.locktime >= this.auctionDeadline, 'auction is not over yet')
+
+        // Check signature of the auctioneer.
+        assert(this.checkSig(sig, this.auctioneer), 'signature check failed')
+    }
+
+    // User defined transaction builder for calling function `bid`
+    static bidTxBuilder(options: MethodCallOptions<Auction>, bidder: PubKey, bid: bigint): Promise<ContractTransaction> {
+        const current = options.current
+
+        const nextInstance = current.next()
+        nextInstance.bidder = bidder
+
+        const unsignedTx: Transaction = new Transaction()
+            // add contract input
+            .addInput(current.buildContractInput(options.fromUTXO))
+            // build next instance output
+            .addOutput(new Transaction.Output({script: nextInstance.lockingScript, satoshis: Number(bid),}))
+            // build refund output
+            .addOutput(
+                new Transaction.Output({
+                    script: Script.fromHex(Utils.buildPublicKeyHashScript(hash160(current.bidder))),
+                    satoshis: options.fromUTXO?.satoshis ?? current.from.tx.outputs[current.from.outputIndex].satoshis,
+                })
+            )
+            // build change output
+            .change(options.changeAddress)
+
+        return Promise.resolve({
+            tx: unsignedTx,
+            atInputIndex: 0,
+            nexts: [
+                {
+                    instance: nextInstance,
+                    atOutputIndex: 0,
+                    balance: Number(bid),
+                },
+            ],
+        })
+    }
+}
+```

bitcoin-basics.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+# Bitcoin Basics
+
+If you are new to Bitcoin development, we recommend exploring the resources listed in this section. While not an absolute prerequisite, going over these guides will provide a clearer understanding of key concepts and make it easier to begin developing sCrypt smart contracts.
+
+If you are already familiar with the basics of Bitcoin, you can skip ahead to the [How to Write a Contract section](../how-to-write-a-contract/how-to-write-a-contract.md).
+
+## Useful Resources for Learning Bitcoin Fundamentals
+
+If you want to learn more about the fundamentals of Bitcoin, consider exploring the following resources:
+- [BSV Academy - Bitcoin Theory](https://bitcoinsv.academy/course/bitcoin-theory)
+- [BSV Academy - Bitcoin Essentials](https://bitcoinsv.academy/bitcoin-essentials)
+- [Satolearn](https://www.satolearn.com/overview)
+- [BSV Wiki](https://wiki.bitcoinsv.io/index.php/Main_Page)

bsv.md

@@ -0,0 +1,217 @@
+---
+sidebar_position: 1
+---
+# The BSV submodule
+
+sCrypt exports a submodule named `bsv` which is an interface that helps you manage low-level things for the Bitcoin blockchain, such as creating key pairs, building, signing and serializing Bitcoin transactions and more.
+
+In the context of sCrypt, it is mainly used for managing key pairs and defining custom transaction builders, as demonstrated in [this section](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md).
+
+The goal of this section is to guide you through the basics of using the `bsv` submodule.
+
+## Importing
+
+You can import the `bsv` submodule like so:
+
+```ts
+import { bsv } from 'scrypt-ts'
+```
+
+## Private Keys
+
+A private key object is essentially just a wrapper around a 256-bit integer.
+
+You can generate a Bitcoin private key from a random value:
+
+```ts
+const privKey = bsv.PrivateKey.fromRandom()
+// Same as: const privKey = bsv.PrivateKey.fromRandom(bsv.Network.mainnet)
+```
+
+This will generate a private key for the Bitcoin main network. To create a key for the test network (also referred to as "testnet"), do the following instead:
+
+```ts
+const privKey = bsv.PrivateKey.fromRandom(bsv.Networks.testnet)
+```
+
+The main difference between a mainnet and a testnet key is how they get serialized. Check out [this page](https://wiki.bitcoinsv.io/index.php/Wallet_Import_Format_(WIF)) which explains this in detail.
+
+You can also create key object from serialized keys:
+```ts
+const privKey = bsv.PrivateKey.fromWIF('cVDFHtcTU1wn92AkvTyDbtVqyUJ1SFQTEEanAWJ288xvA7TEPDcZ')
+const privKey2 = bsv.PrivateKey.fromString('e3a9863f4c43576cdc316986ba0343826c1e0140b0156263ba6f464260456fe8')
+```
+
+You can see the decimal value of the private key the following way:
+```ts
+console.log(privKey.bn.toString())
+```
+
+> **Warning**
+> Private keys should be carefully stored and never be publicly revealed. Otherwise it may lead to loss of funds.
+
+## Public Keys
+
+A public key is a key that is derived from a private key and can be shared publicly. Mathematically, a public key is a point on the default elliptic curve that Bitcoin uses, named [`SECP256K1`](https://wiki.bitcoinsv.io/index.php/Secp256k1). It is the curve's base point multiplied by the value of the private key.
+
+You can get the public key corresponding to a private key the following way:
+
+```ts
+const privKey = bsv.PrivateKey.fromRandom(bsv.Networks.testnet)
+const pubKey = privKey.toPublicKey()
+```
+
+Same as with private key you can serialize and deserialize public keys:
+
+```ts
+const pubKey = bsv.PublicKey.fromHex('03a687b08533e37d5a6ff5c8b54a9869d4def9bdc2a4bf8c3a5b3b34d8934ccd17')
+
+console.log(pubKey.toHex())
+// 03a687b08533e37d5a6ff5c8b54a9869d4def9bdc2a4bf8c3a5b3b34d8934ccd17
+```
+
+## Addresses
+
+You can get a Bitcoin address from either the private key or the public key:
+
+```ts
+const privKey = bsv.PrivateKey.fromRandom(bsv.Networks.testnet)
+const pubKey = privKey.toPublicKey()
+
+console.log(privKey.toAddress())
+// mxRjX2uxHHmS4rdSYcmCcp2G91eseb5PpF
+console.log(pubKey.toAddress())
+// mxRjX2uxHHmS4rdSYcmCcp2G91eseb5PpF
+```
+
+Read [this wiki page](https://wiki.bitcoinsv.io/index.php/Bitcoin_address) for more information on how Bitcoin addresses get constructed.
+
+## Hash Functions
+
+The `bsv` submodule offers various hash functions that are commonly used in Bitcoin. You can use them like so:
+
+```ts
+const hashString = bsv.crypto.Hash.sha256(Buffer.from('this is the data I want to hash')).toString('hex')
+console.log(hashString)
+// f88eec7ecabf88f9a64c4100cac1e0c0c4581100492137d1b656ea626cad63e3
+```
+
+The hash functions available in the `bsv` submodule are:
+
+| Hash Function | Output Length | Description                                                |
+|---------------|--------------|------------------------------------------------------------|
+| sha256        | 32 bytes     | The SHA256 hash.                                           |
+| sha256sha256  | 32 bytes     | The SHA256 hash of the SHA256 hash. Used for blocks and transactions. |
+| sha512        | 64 bytes     | The SHA512 hash. Commonly used in applications.             |
+| sha1          | 20 bytes     | The SHA1 hash.                                             |
+| ripemd160     | 20 bytes     | The RIPEMD160 hash.                                        |
+| sha256ripemd160 | 20 bytes     | The RIPEMD160 hash of the SHA256 hash. Used in Bitcoin addresses. |
+
+Note however, that these [bsv.js hash functions](https://github.com/moneybutton/bsv/blob/master/lib/hash.js) should not be confused with [sCrypt's native hash functions](https://scrypt.io/docs/reference/#hashing-functions). These functions cannot be used in a smart contract method.
+
+## Constructing Transactions
+
+The `bsv` submodule offers a flexible system for constructing Bitcoin transactions. Users are able to define scripts, transaction inputs and outputs, and a whole transaction including its metadata. For a complete description of Bitcoins transaction format, please read [this wiki page](https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions).
+
+As an exercise let's construct a simple [P2PKH](https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions#Pay_to_Public_Key_Hash_.28P2PKH.29) transaction from scratch and sign it.
+
+> **Note:**
+> As you will notice further in these docs, most of these steps won't be needed in a regular smart contract development workflow as sCrypt already does a lot of heavy lifting for you. This section serves more as a deeper look on what is happening under the hood.
+
+You can create an empty transaction like this:
+```ts
+let tx = new bsv.Transaction()
+```
+
+Because the transaction will need an input that provides it with some funds, we can use the `from` function to add one that unlocks the specified [UTXO](https://wiki.bitcoinsv.io/index.php/UTXO):
+
+```ts
+let tx = new bsv.Transaction()
+    .from({
+        // TXID that contains the output you want to unlock:
+        txId: 'f50b8c6dedea6a4371d17040a9e8d2ea73d369177737fb9f47177fbda7d4d387',
+        // Index of the UTXO:
+        outputIndex: 0,
+        // Script of the UTXO. In this case it's a regular P2PKH script:
+        script: bsv.Script.fromASM('OP_DUP OP_HASH160 fde69facc20be6eee5ebf5f0ae96444106a0053f OP_EQUALVERIFY OP_CHECKSIG').toHex(),
+        // Value locked in the UTXO in satoshis:
+        satoshis: 99904
+    })
+```
+
+Now, the transaction needs an output that will pay to the address `mxXPxaRvFE3178Cr6KK7nrQ76gxjvBQ4UQ` in our example:
+
+```ts
+let tx = new bsv.Transaction()
+    .from({
+        // TXID that contains the output you want to unlock:
+        txId: 'f50b8c6dedea6a4371d17040a9e8d2ea73d369177737fb9f47177fbda7d4d387',
+        // Index of the UTXO:
+        outputIndex: 0,
+        // Script of the UTXO. In this case it's a regular P2PKH script:
+        script: bsv.Script.fromASM('OP_DUP OP_HASH160 fde69facc20be6eee5ebf5f0ae96444106a0053f OP_EQUALVERIFY OP_CHECKSIG').toHex(),
+        // Value locked in the UTXO in satoshis:
+        satoshis: 99904
+    }).addOutput(
+        new bsv.Transaction.Output({
+            script: bsv.Script.buildPublicKeyHashOut('mxXPxaRvFE3178Cr6KK7nrQ76gxjvBQ4UQ'),
+            satoshis: 99804,
+        })
+    )
+```
+
+Notice how the output value is 100 less than the value of the UTXO we're unlocking. This difference is the [transaction fee](https://wiki.bitcoinsv.io/index.php/Transaction_fees) (sometimes also called the miner fee).
+
+### Signing
+
+OK, now that we have the transaction constructed, it's time to sign it. First, we need to seal the transaction, so it will be ready to sign. Then we call the `sign` function, which takes the private key that can unlock the UTXO we passed to the `from` function. In our example, this is the private key that corresponds to the address `n4fTXc2kaKXHyaxmuH5FTKiJ8Tr4fCPHFy`:
+
+```ts
+tx = tx.seal().sign('cNSb8V7pRt6r5HrPTETq2Li2EWYEjA7EcQ1E8V2aGdd6UzN9EuMw')
+```
+
+Viola! Thats it. This will add the necessary data to the transaction's input script. That being the signature along with the public key of our signing key.
+
+Now our transaction is ready to be posted to the blockchain. You can serialize the transaction the following way:
+
+```ts
+console.log(tx.serialize())
+```
+
+For broadcasting, you can use any provider you like. For demo purposes you can simply paste the serialized transaction [here](https://test.whatsonchain.com/broadcast).
+
+### OP_RETURN Scripts
+
+In case you would like to put some arbitrary data on-chain, without any locking logic, you can use transaction outputs with an [OP_RETURN](https://wiki.bitcoinsv.io/index.php/OP_RETURN) script.
+
+An example of an OP_RETURN script written in ASM format is this:
+
+```
+OP_FALSE OP_RETURN 734372797074
+```
+
+In effect, the opcodes `OP_FALSE OP_RETURN` will make the script unspendable. After them we can insert arbitrary chunks of data. The `734372797074` is actually the string `sCrypt` encoded as an `utf-8` hexadecimal string.
+
+```js
+console.log(Buffer.from('sCrypt').toString('hex'))
+// 734372797074
+```
+
+An OP_RETURN script can also contain more than a single chunk of data:
+```
+OP_FALSE OP_RETURN 48656c6c6f 66726f6d 734372797074
+```
+
+The `bsv` submodule offers a convenient function to construct such scripts:
+
+```ts
+const opRetScript: bsv.Script = bsv.Script.buildSafeDataOut(['Hello', 'from', 'sCrypt'])
+```
+
+We can add the resulting `bsv.Script` object to an output as we showed [above](#constructing-transactions).
+
+
+## References
+
+- Take a look at the full [`bsv` submodule reference](../reference/modules/bsv) for a full list of what functions it provides.
+- As the `bsv` submodule is based on MoneyButton's library implementation, take a look at their [video tutorial series](https://www.youtube.com/watch?v=bkGiCjYBpJE&list=PLwj1dNv7vWsMrjrWeiQEelbKTI3Lrmvqp&index=1). Although do keep in mind that some things might be slightly different as it's an old series.

built-ins.md

@@ -0,0 +1,716 @@
+---
+sidebar_position: 4
+---
+
+# Built-ins
+
+## Global Functions
+
+The following functions come with `sCrypt`.
+
+### Assert
+
+- `assert(condition: boolean, errorMsg?: string)` Throw an `Error` with the optional error message if `condition` is `false`. Otherwise, nothing happens.
+
+```ts
+assert(1n === 1n)        // nothing happens
+assert(1n === 2n)        // throws Error('Execution failed')
+assert(false, 'hello')   // throws Error('Execution failed, hello')
+```
+
+### Fill
+
+- `fill(value: T, length: number): T[length] ` Returns an `FixedArray` with all `size` elements set to `value`, where `value` can be any type. 
+
+:::note
+`length` must be a [compiled-time constant](./how-to-write-a-contract.md#compile-time-constant).
+:::
+
+
+```ts
+// good
+fill(1n, 3) // numeric literal 3
+fill(1n, M) // const M = 3
+fill(1n, Demo.N) // `N` is a static readonly property of class `Demo`
+```
+
+### Math
+
+- `abs(a: bigint): bigint` Returns the absolute value of `a`.
+
+```ts
+abs(1n)  // 1n
+abs(0n)  // 0n
+abs(-1n) // 1n
+```
+
+- `min(a: bigint, b: bigint): bigint` Returns the smallest of `a` and `b`.
+
+```ts
+min(1n, 2n) // 1n
+```
+
+- `max(a: bigint, b: bigint): bigint` Returns the lagest of `a` and `b`.
+
+```ts
+max(1n, 2n) // 2n
+```
+
+- `within(x: bigint, min: bigint, max: bigint): boolean` Returns `true` if `x` is within the specified range (left-inclusive and right-exclusive), `false` otherwise.
+
+```ts
+within(0n, 0n, 2n) // true
+within(1n, 0n, 2n) // true
+within(2n, 0n, 2n) // false
+```
+
+### Hashing
+
+- `ripemd160(a: ByteString): Ripemd160` Returns the [RIPEMD160](https://en.wikipedia.org/wiki/RIPEMD) hash result of `a`.
+- `sha1(a: ByteString): Sha1` Returns the [SHA1](https://en.wikipedia.org/wiki/SHA-1) hash result of `a`.
+- `sha256(a: ByteString): Sha256` Returns the [SHA256](https://www.movable-type.co.uk/scripts/sha256.html) hash result of `a`.
+- `hash160(a: ByteString): Ripemd160` Actually returns `ripemd160(sha256(a))`
+- `hash256(a: ByteString): Sha256` Actually returns `sha256(sha256(a))`
+
+### ByteString Operations
+
+- `int2ByteString(n: bigint, size?: bigint): ByteString` If `size` is omitted, convert `n` is converted to a `ByteString` in [sign-magnitude](https://en.wikipedia.org/wiki/Signed_number_representations#Sign%E2%80%93magnitude) little endian format, with as few bytes as possible (a.k.a., minimally encoded). Otherwise, converts the number `n` to a `ByteString` of the specified size, including the sign bit; fails if the number cannot be accommodated.
+
+```ts
+// as few bytes as possible
+int2ByteString(128n)   // '8000', little endian
+int2ByteString(127n)   // '7f'
+int2ByteString(0n)     // ''
+int2ByteString(-1n)    // '81'
+int2ByteString(-129n)  // '8180', little endian
+
+// specified size
+int2ByteString(1n, 3n)        // '010000', 3 bytes
+int2ByteString(-129n, 3n)     // '810080', 3 bytes
+
+// Error: -129 cannot fit in 1 byte
+int2ByteString(-129n, 1n)
+```
+
+- `byteString2Int(a: ByteString): bigint` Convert ByteString in sign-magnitude little endian format to bigint.
+
+```ts
+byteString2Int(toByteString('8000'))    // 128n
+byteString2Int(toByteString(''))        // 0n
+byteString2Int(toByteString('00'))      // 0n
+byteString2Int(toByteString('81'))      // -1n
+
+byteString2Int(toByteString('010000'))  // 1n
+byteString2Int(toByteString('810080'))  // -129n
+```
+
+- `len(a: ByteString): number` Returns the byte length of `a`. 
+
+```ts
+const s1 = toByteString('0011', false) // '0011', 2 bytes
+len(s1) // 2
+
+const s2 = toByteString('hello', true) // '68656c6c6f', 5 bytes
+len(s2) // 5
+```
+
+- `reverseByteString(b: ByteString, size: number): ByteString` Returns reversed bytes of `b` which is of `size` bytes. It is often useful when converting a number between little-endian and big-endian.
+
+:::note
+`size` must be a [compiled-time constant](./how-to-write-a-contract.md#compile-time-constant).
+:::
+
+```ts
+const s1 = toByteString('793ff39de7e1dce2d853e24256099d25fa1b1598ee24069f24511d7a2deafe6c') 
+reverseByteString(s1, 32) // 6cfeea2d7a1d51249f0624ee98151bfa259d095642e253d8e2dce1e79df33f79
+```
+
+- `slice(byteString: ByteString, start: BigInt, end?: BigInt): ByteString` return a substring from `start` to, but not including, `end`. If `end` is not specified, the substring continues to the last byte.
+
+```ts
+const message = toByteString('001122')
+slice(message, 1n) // '1122'
+slice(message, 1n, 2n) // '11'
+```
+
+### Bitwise Operator
+
+Bigint in the Bitcoin is stored in [sign–magnitude format](https://en.wikipedia.org/wiki/Signed_number_representations#Sign%E2%80%93magnitude), not [two's complement format](https://en.wikipedia.org/wiki/Signed_number_representations#Two's_complement) commonly used. If the operands are all nonnegative, the result of the operation is consistent with TypeScript's bitwise operator, except `~`. Otherwise, the operation results may be inconsistent and thus undefined. It is strongly recommended to **NEVER** apply bitwise operations on negative numbers.
+
+- `and(x: bigint, y: bigint): bigint` Bitwise AND
+
+```ts
+and(13n, 5n) // 5n
+and(0x0a32c845n, 0x149f72n) // 0x00108840n, 1083456n
+```
+
+- `or(x: bigint, y: bigint): bigint` Bitwise OR
+
+```ts
+or(13n, 5n) // 13n
+or(0x0a32c845n, 0x149f72n) // 0xa36df77n, 171368311n
+```
+
+- `xor(x: bigint, y: bigint): bigint` Bitwise XOR
+
+```ts
+xor(13n, 5n) // 8n
+xor(0x0a32c845n, 0x149f72n) // 0x0a265737n, 170284855n
+```
+
+- `invert(x: bigint): bigint` Bitwise NOT
+
+```ts
+invert(13n)  // -114n
+```
+
+- `lshift(x: bigint, n: bigint): bigint` Arithmetic left shift, returns `x * 2^n`.
+
+```ts
+lshift(2n, 3n)   // 16n
+```
+
+- `rshift(x: bigint, n: bigint): bigint` Arithmetic right shift, returns `x / 2^n`.
+
+```ts
+rshift(21n, 3n)    // 2n
+rshift(1024n, 11n) // 0n
+```
+
+### Exit
+
+- `exit(status: boolean): void` Call this function will terminate contract execution. If `status` is `true` then the contract succeeds; otherwise, it fails.
+
+## `SmartContract` Methods
+
+The following `@methods` come with the `SmartContract` base class.
+
+### `compile`
+
+Function `static async compile(): Promise<TranspileError[]>` compiles the contract and returns transpile errors if compiling fails.
+
+```ts
+// returns transpile errors if compiling fails
+const transpileErrors = await Demo.compile()
+```
+
+### `scriptSize`
+
+Function `get scriptSize(): number` returns the byte length of the contract locking script.
+
+```ts
+const demo = new Demo()
+const size = demo.scriptSize
+```
+
+### `loadArtifact`
+
+Function `static loadArtifact(artifact: MergedArtifact)` loads the contract artifact file in order to rebuild a contract instance, it's usually called at the front end.
+
+```ts
+import { TicTacToe } from './contracts/tictactoe';
+var artifact = require('../artifacts/src/contracts/tictactoe.json');
+TicTacToe.loadArtifact(artifact);
+```
+
+You may visit [here](https://academy.scrypt.io/en/courses/Build-a-Tic-tac-toe-Game-with-sCrypt-614c387bc0974f55df5af1e5/lessons/2/chapters/1) for more details about how to add a front end to a contract.
+
+### `checkSig`
+
+Function `checkSig(signature: Sig, publicKey: PubKey): boolean` verifies an ECDSA signature. It takes two inputs: an ECDSA signature and a public key. 
+
+It returns if the signature matches the public key.
+
+:::caution
+All signature checking functions (`checkSig` and `checkMultiSig`) follow the [**NULLFAIL** rule](https://github.com/bitcoin/bips/blob/master/bip-0146.mediawiki#NULLFAIL): if the signature is invalid, the entire contract aborts and fails immediately, unless the signature is an empty ByteString, in which case these functions return `false`.
+:::
+
+For example, Pay-to-Public-Key-Hash ([P2PKH](https://learnmeabitcoin.com/guide/p2pkh)) can be implemented as below.
+
+```ts
+class P2PKH extends SmartContract {
+  // public key hash of the recipient.
+  @prop()
+  readonly pubKeyHash: PubKeyHash
+
+  constructor(pubKeyHash: PubKeyHash) {
+    super(...arguments)
+    this.pubKeyHash = pubKeyHash
+  }
+
+  @method()
+  public unlock(sig: Sig, pubkey: PubKey) {
+    // check if the passed public key belongs to the specified public key hash
+    assert(hash160(pubkey) == this.pubKeyHash, 'public key hashes are not equal')
+    // check signature validity
+    assert(this.checkSig(sig, pubkey), 'signature check failed')
+  }
+}
+```
+
+### `checkMultiSig`
+
+Function `checkMultiSig(signatures: Sig[], publickeys: PubKey[]): boolean` verifies an array of ECDSA signatures. It takes two inputs: an array of ECDSA signatures and an array of public keys.
+
+The function compares the first signature against each public key until it finds an ECDSA match. Starting with the subsequent public key, it compares the second signature against each remaining public key until it finds an ECDSA match. The process is repeated until all signatures have been checked or not enough public keys remain to produce a successful result. All signatures need to match a public key. Because public keys are not checked again if they fail any signature comparison, signatures must be placed in the `signatures` array using the same order as their corresponding public keys were placed in the `publickeys` array. If all signatures are valid, `true` is returned, `false` otherwise.
+
+```ts
+class MultiSigPayment extends SmartContract {
+  // public key hashes of the 3 recipients
+  @prop()
+  readonly pubKeyHashes: FixedArray<PubKeyHash, 3>
+
+  constructor(pubKeyHashes: FixedArray<PubKeyHash, 3>) {
+    super(...arguments)
+    this.pubKeyHashes = pubKeyHashes
+  }
+
+  @method()
+  public unlock(
+      signatures: FixedArray<Sig, 3>, 
+      publicKeys: FixedArray<PubKey, 3>
+    ) {
+    // check if the passed public keys belong to the specified public key hashes
+    for (let i = 0; i < 3; i++) {
+      assert(hash160(publicKeys[i]) == this.pubKeyHashes[i], 'public key hash mismatch¸')
+    }
+    // validate signatures
+    assert(this.checkMultiSig(signatures, publicKeys), 'checkMultiSig failed')
+  }
+}
+```
+
+### `buildStateOutput`
+
+Function `buildStateOutput(amount: bigint): ByteString` creates an output containing the latest state. It takes an input: the number of satoshis in the output.
+
+```ts
+class Counter extends SmartContract {
+  // ...
+
+  @method(SigHash.ANYONECANPAY_SINGLE)
+  public incOnChain() {
+    // ... update state
+      
+    // construct the new state output 
+    const output: ByteString = this.buildStateOutput(this.ctx.utxo.value)
+
+    // ... verify outputs of current tx
+  }
+}
+```
+
+### `buildChangeOutput`
+
+Function `buildChangeOutput(): ByteString` creates a P2PKH change output. It will calculate the change amount (`this.changeAmount`) automatically, and use the signer's address by default, unless `changeAddress` field is explicitly set in `MethodCallOptions`.
+
+```ts
+class Auction extends SmartContract {
+
+  // ...
+
+  @method()
+  public bid(bidder: PubKeyHash, bid: bigint) {
+    
+    // ...
+
+    // Auction continues with a higher bidder.
+    const auctionOutput: ByteString = this.buildStateOutput(bid)
+
+    // Refund previous highest bidder.
+    const refundOutput: ByteString = Utils.buildPublicKeyHashOutput(
+        highestBidder,
+        highestBid
+    )
+    let outputs: ByteString = auctionOutput + refundOutput
+
+    // Add change output.
+    outputs += this.buildChangeOutput()
+
+    assert(hash256(outputs) == this.ctx.hashOutputs, 'hashOutputs check failed')
+  }
+}
+
+const { tx: callTx, atInputIndex } = await auction.methods.bid(
+  PubKeyHash(toHex(publicKeyHashNewBidder)),
+  BigInt(balance + 1),
+  {
+    fromUTXO: getDummyUTXO(balance),
+    changeAddress: addressNewBidder, // specify the change address of method calling tx explicitly
+  } as MethodCallOptions<Auction>
+)
+```
+
+:::note
+If you use a [customized call tx builder](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md), you must explicitly set the change output of the transaction in the builder beforehand. Otherwise, you cannot call `this.changeAmount` or `this.buildChangeOutput`  in the contract.
+:::
+
+```ts
+const unsignedTx: bsv.Transaction = new bsv.Transaction()
+  // add inputs and outputs
+  // ...
+  // add change output
+  // otherwise you cannot call `this.changeAmount` and `this.buildChangeOutput` in the contract
+  .change(options.changeAddress);
+```
+
+### `fromTx`
+
+Function `static fromTx(tx: bsv.Transaction, atOutputIndex: number, offchainValues?: Record<string, any>)` creates an instance with its state synchronized to a given transaction output, identified by `tx` the transaction and `atOutputIndex` the output index. It is needed to [create an up-to-date instance of a contract](./../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#create-a-smart-contract-instance-from-a-transaction).
+
+```ts
+// create an instance from a transaction output
+const instance = ContractName.fromTx(tx, atOutputIndex)
+
+// we're good here, the `instance` is state synchronized with the on-chain transaction
+```
+
+If the contract contains @prop's of type `HashedMap` or `HashedSet`, the values of all these properties at this transaction must be passed in the third argument.
+
+```ts
+// e.g. the contract has two stateful properties of type `HashedMap` or `HashedSet`
+// @prop(true) mySet: HashedSet<bigint>
+// @prop() myMap: HashedMap<bigint, bigint>
+const instance = ContractName.fromTx(tx, atOutputIndex, {
+    // pass the values of all these properties at the transaction moment
+    'mySet': currentSet,
+    'myMap': currentMap,
+})
+```
+
+### `buildDeployTransaction`
+
+Function `async buildDeployTransaction(utxos: UTXO[], amount: number, changeAddress?: bsv.Address | string): Promise<bsv.Transaction>` creates a tx to deploy the contract. The first parameter `utxos` represents one or more [P2PKH](https://learnmeabitcoin.com/technical/p2pkh) inputs for paying transaction fees. The second parameter `amount` is the balance of contract output. The last parameter `changeAddress` is optional and represents a change address. Users override it to [cutomize a deployment tx](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md#customize) as below.
+
+
+```ts
+override async buildDeployTransaction(utxos: UTXO[], amount: number, changeAddress?: bsv.Address | string): Promise<bsv.Transaction> {
+    const deployTx = new bsv.Transaction()
+      // add p2pkh inputs for paying tx fees
+      .from(utxos) 
+      // add contract output
+      .addOutput(new bsv.Transaction.Output({
+        script: this.lockingScript,
+        satoshis: amount,
+      }))
+    // add the change output if passing `changeAddress`
+    if (changeAddress) {
+      deployTx.change(changeAddress);
+      if (this._provider) {
+        deployTx.feePerKb(await this.provider.getFeePerKb());
+      }
+    }
+
+    return deployTx;
+  }
+```
+
+### `bindTxBuilder`
+
+Function `bindTxBuilder(methodName: string, txBuilder: MethodCallTxBuilder<SmartContract>):void` binds the customized transaction builder `MethodCallTxBuilder`, which returns a `ContractTransation`, to a contract public `@method` identified by `methodName`.
+
+```ts
+
+/**
+ * A transaction builder.
+ * The default transaction builder only supports fixed-format call transactions. 
+ * Some complex contracts require a custom transaction builder to successfully call the contract.
+ */
+export interface MethodCallTxBuilder<T extends SmartContract> {
+  (current: T, options: MethodCallOptions<T>, ...args: any): Promise<ContractTransaction>
+}
+
+
+// bind a customized tx builder for the public method `instance.unlock()`
+instance.bindTxBuilder("unlock", (options: MethodCallOptions<T>, ...args: any) => {
+  // ...
+})
+```
+
+You may visit [here](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md#customize-1) to see more details on how to customize tx builder.
+
+
+### `multiContractCall`
+
+When the `@method`s of multiple contracts is called in a transaction, the transaction builders for each contract collectively construct the `ContractTransation`. Function `static async multiContractCall(partialContractTx: ContractTransaction, signer: Signer): Promise<MultiContractTransaction>` signs and broadcasts the final transaction.
+
+```ts
+const partialContractTx1 = await counter1.methods.incrementOnChain(
+    {
+        multiContractCall: true,
+    } as MethodCallOptions<Counter>
+)
+
+const partialContractTx2 = await counter2.methods.incrementOnChain(
+    {
+        multiContractCall: true,
+        partialContractTx: partialContractTx1
+    } as MethodCallOptions<Counter>
+);
+
+const {tx: callTx, nexts} = await SmartContract.multiContractCall(partialContractTx2, signer)
+
+
+console.log('Counter contract counter1, counter2 called: ', callTx.id)
+```
+
+
+
+## Standard Libraries
+
+`sCrypt` comes with standard libraries that define many commonly used functions.
+
+### `Utils`
+
+The `Utils` library provides a set of commonly used utility functions.
+
+- `static toLEUnsigned(n: bigint, l: bigint): ByteString` Convert the signed integer `n` to an unsigned integer of `l` bytes, in sign-magnitude little endian format.
+
+```ts
+Utils.toLEUnsigned(10n, 3n)   // '0a0000'
+Utils.toLEUnsigned(-10n, 2n)  // '0a00'
+```
+
+- `static fromLEUnsigned(bytes: ByteString): bigint` Convert ByteString to unsigned integer.
+
+```ts
+Utils.fromLEUnsigned(toByteString('0a00'))  // 10n
+Utils.fromLEUnsigned(toByteString('8a'))    // 138n, actually converts 8a00 to unsigned integer
+```
+
+- `static readVarint(buf: ByteString): ByteString` Read a [VarInt](https://learnmeabitcoin.com/technical/varint) field from `buf`.
+
+```ts
+Utils.readVarint(toByteString('0401020304')) // '01020304'
+```
+
+- `static writeVarint(buf: ByteString): ByteString` Convert `buf` to a [VarInt](https://learnmeabitcoin.com/technical/varint) field, including the preceding length.
+
+```ts
+Utils.writeVarint(toByteString('010203')) // '03010203'
+```
+
+- `static buildOutput(outputScript: ByteString, outputSatoshis: bigint): ByteString` Build a transaction output with the specified script and satoshi amount.
+
+```ts
+const lockingScript = toByteString('01020304')
+Utils.buildOutput(lockingScript, 1n) // '01000000000000000401020304'
+```
+
+- `static buildPublicKeyHashScript(pubKeyHash: PubKeyHash ): ByteString` Build a [Pay to Public Key Hash (P2PKH)](https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions#Pay_to_Public_Key_Hash_.28P2PKH.29) script from a public key hash.
+
+```ts
+const pubKeyHash = PubKeyHash(toByteString('0011223344556677889900112233445566778899'))
+Utils.buildPublicKeyHashScript(pubKeyHash) // '76a914001122334455667788990011223344556677889988ac'
+```
+
+- `static buildPublicKeyHashOutput(pubKeyHash: PubKeyHash, amount: bigint): ByteString` Build a P2PKH output from the public key hash.
+
+```ts
+const pubKeyHash = PubKeyHash(toByteString('0011223344556677889900112233445566778899'))
+Utils.buildPublicKeyHashOutput(pubKeyHash, 1n) // '01000000000000001976a914001122334455667788990011223344556677889988ac'
+```
+
+- `static buildOpreturnScript(data: ByteString): ByteString` Build a data-carrying [FALSE OP_RETURN](https://wiki.bitcoinsv.io/index.php/OP_RETURN) script from `data` payload.
+
+```ts
+const data = toByteString('hello world', true)
+Utils.buildOpreturnScript(data) // '006a0b68656c6c6f20776f726c64'
+```
+
+### `HashedMap`
+
+
+`HashedMap` provides a map/hashtable-like data structure. It is different to use `HashedMap` in on-chain and off-chain context.
+
+#### On-chain
+
+The main difference between `HashedMap` and other data types we’ve [previously introduced](../how-to-write-a-contract/#data-types) is that it does NOT store raw data (i.e., keys and values) in the contract on the blockchain. It stores their hashed values instead, to minimize on-chain storage, which is expensive.
+
+These guidelines must be followed when using `HashedMap` in a contract `@method`, i.e., on-chain context.
+
+* Only the following methods can be called.
+
+	- `set(key: K, val: V): HashedMap`: Adds a new element with a specified key and value. If an element with the same key already exists, the element will be updated.
+	- `canGet(key: K, val: V): boolean`: Returns `true` if the specified **key and value pair** exists, otherwise returns `false`.
+	- `has(key: K): boolean`: Returns `true` if the specified key exists, otherwise returns `false`.
+  - `delete(key: K): boolean`: Returns `true` if a key exists and has been removed, otherwise returns `false`.
+	- `clear(): void`: Remove all key and value pairs.
+	- `size: number`: Returns the number of elements.
+
+:::note 
+`get()` is not listed, since the value itself is not stored and thus must be passed in and verified using `canGet()`.
+:::
+
+* The aforementioned methods can only be used in public `@method`s, NOT in non-public `@method`s, including constructors.
+
+* `HashedMap` can be used as an `@prop`, either stateful or not:
+
+```ts
+@prop() map: HashedMap<KeyType, ValueType>; // valid
+@prop(true) map: HashedMap<KeyType, ValueType> // also valid
+```
+
+* It CANNOT be used as a `@method` parameter, regardless of public or not:
+
+```ts
+@method public unlock(map: HashedMap<KeyType, ValueType>) // invalid as a parameter type
+@method foo(map: HashedMap<KeyType, ValueType>) // invalid as a parameter type
+```
+
+* No nesting is allowed currently. That is, key and value cannot contain a `HashedMap`.
+```ts
+type Map1 = HashedMap<KeyType1, ValueType1>
+HashedMap<KeyType2, Map1> // invalid
+HashedMap<Map1, ValueType2> // invalid
+
+type KeyType = {
+  key1: KeyType1
+  key2: KeyType2
+}
+HashedMap<KeyType, ValueType> // valid
+```
+
+A full example may look like this:
+
+```ts
+class MyContract extends SmartContract {
+  @prop(true)
+  myMap: HashedMap<bigint, bigint>;
+
+  // HashedMap can be a parameter in constructor
+  constructor(map: HashedMap<bigint, bigint>) {
+    // assignment is ok, but not calling method
+    this.myMap = map;
+  }
+
+  @method()
+  public unlock(key: bigint, val: bigint) {
+    this.myMap.set(key, val);
+    assert(this.myMap.has(key));
+    assert(this.myMap.canGet(key, val));
+    assert(this.myMap.delete(key));
+    assert(!this.myMap.has(key));
+  }
+}
+```
+
+#### Off-chain
+
+`HashedMap` acts just like the JavaScript/TypeScript [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) when used in off-chain code (that is, not in a contract's `@method`). For example, you can create an instance like this:
+
+```ts
+// create an empty map
+let hashedMap = new HashedMap<bigint, ByteString>();
+
+// create from (key,value) pairs
+let hashedMap1 = new HashedMap([['key1', 'value1'], ['key2', 'value2']]);
+```
+
+Also, you can call its functions like this:
+
+```ts
+hashedMap.set(key, value);
+const v = hashedMap.get(key);   // <----
+hashedMap.has(key);
+hashedMap.delete(key);
+...
+```
+:::note
+`get()` can be called since the HashedMap stores the original key and value off chain.
+:::
+
+Only when the key is an object is `HashedMap` different from `Map`. `HashedMap` will treat two keys the same if they have the same values, while `Map` will only if they reference the same object. For instance:
+
+```ts
+interface ST {
+  a: bigint;
+}
+
+let map = new Map<ST, bigint>();
+map.set({a: 1n}, 1n);
+map.set({a: 1n}, 2n);
+console.log(map.size); // output ‘2’ cause two keys {a: 1n} reference differently
+console.log(map.get({a: 1n})); // output ‘undefined’
+
+
+let hashedMap = new HashedMap<ST, bigint>();
+hashedMap.set({a: 1n}, 1n);
+hashedMap.set({a: 1n}, 2n);
+console.log(hashedMap.size); // output ‘1’
+console.log(hashedMap.get({a: 1n})); // output ‘2n’
+```
+
+### `HashedSet`
+
+
+`HashedSet` library provides a set-like data structure. It can be regarded as a special `HashedMap` where a value is the same with its key and is thus omitted. Values are hashed before being stored in contracts on the blockchain, as in `HashedMap`.
+
+#### On-chain
+
+When used in public `@method`s, `HashedSet` also has almost all of the same restrictions as `HashedMap`. Except for the methods on its own whitelist that can be called in `@method`s as following:
+
+- `add(value: T): HashedSet`: Inserts a new element with a specified value in to a set, if there isn't an element with the same value already in the set.
+
+- `has(value: T): boolean`: Returns `true` if an element with the specified value exists in the set, otherwise returns `false`.
+
+- `delete(value: T): boolean`: Returns `true` if an element in the Set existed and has been removed, or false if the element does not exist.
+
+- `clear(): void`: Delete all entries of the set.
+
+- `size: number`: Returns the size of set, i.e. the number of the entries it contains.
+
+
+#### Off-chain
+
+`HashedSet` can be used the same as a JavaScript `Set` in off-chain code .
+
+```ts
+let hashedSet = new HashedSet<bigint>()
+hashedSet.add(1n);
+hashedSet.has(1n);
+hashedSet.delete(1n);
+...
+```
+
+Similar to `HashedMap`, `HashedSet` will treat two objects as identical if their values equal, rather than requiring that they reference to the same object.
+
+```ts
+interface ST {
+  a: bigint;
+}
+
+let set = new Set<ST>();
+set.add({a: 1n});
+set.add({a: 1n});
+console.log(set.size); // output ‘2’
+console.log(set.has({a: 1n})); // output ‘false’
+
+
+let hashedSet = new HashedSet<ST, bigint>();
+hashedSet.add({a: 1n});
+hashedSet.add({a: 1n});
+console.log(hashedSet.size); // output ‘1’
+console.log(hashedSet.has({a: 1n})); // output ‘true’
+```
+
+### `Constants`
+
+`Constants` defines some commonly used constant values.
+
+```ts
+class Constants {
+    // number of string to denote input sequence
+    static readonly InputSeqLen: bigint = BigInt(4);
+    // number of string to denote output value
+    static readonly OutputValueLen: bigint = BigInt(8);
+    // number of string to denote a public key (compressed)
+    static readonly PubKeyLen: bigint = BigInt(33);
+    // number of string to denote a public key hash
+    static readonly PubKeyHashLen: bigint = BigInt(20);
+    // number of string to denote a tx id
+    static readonly TxIdLen: bigint = BigInt(32);
+    // number of string to denote a outpoint
+    static readonly OutpointLen: bigint = BigInt(36);
+}
+```

call-deployed.md

@@ -0,0 +1,122 @@
+---
+sidebar_position: 5
+---
+
+# Interact with a Deployed Contract
+
+## Overview
+In this tutorial, we will interact with a deployed smart contract by calling its public method, in a separate process or by a different party.
+We need to create an instance corresponding to the deployed contract on chain.
+
+## The Smart Contract
+
+We will reuse [the `Counter` contract](../how-to-write-a-contract/stateful-contract.md#create-a-stateful-contract).
+
+```ts
+export class Counter extends SmartContract {
+
+    @prop(true)
+    count: bigint
+
+    constructor(count: bigint) {
+        super(...arguments)
+        this.count = count
+    }
+
+    @method()
+    public incrementOnChain() {
+        // Increment counter.
+        this.increment()
+
+        // Ensure next output will contain this contracts code w
+        // the updated count property.
+        const amount: bigint = this.ctx.utxo.value
+        const outputs: ByteString = this.buildStateOutput(amount) + this.buildChangeOutput()
+        assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+    }
+
+    @method()
+    increment(): void {
+        this.count++
+    }
+}
+```
+
+## Deploy
+
+To deploy the smart contract, we define the following function:
+
+```ts
+async function deploy(initialCount = 100n): Promise<string> {
+    const instance = new Counter(initialCount)
+    await instance.connect(getDefaultSigner())
+    const tx = await instance.deploy(1)
+    console.log(`Counter deployed: ${tx.id}, the count is: ${instance.count}`)
+    return tx.id
+}
+```
+
+The function deploys the contract with a balance of 1 satoshi and returns the TXID of the deployed contract.
+
+## Interact
+Next, we update our deployed smart contract by calling the following function:
+
+```ts
+async function callIncrementOnChain(
+    txId: string,
+    atOutputIndex = 0
+): Promise<string> {
+    // Fetch TX via provider and reconstruct contract instance.
+    const signer = getDefaultSigner()
+    const tx = await signer.connectedProvider.getTransaction(txId)
+    const instance = Counter.fromTx(tx, atOutputIndex)
+
+    await instance.connect(signer)
+
+    const nextInstance = instance.next()
+    nextInstance.increment()
+
+    const { tx: callTx } = await instance.methods.incrementOnChain({
+        next: {
+            instance: nextInstance,
+            balance: instance.balance,
+        },
+    } as MethodCallOptions<Counter>)
+    console.log(`Counter incrementOnChain called: ${callTx.id}, the count now is: ${nextInstance.count}`)
+    return callTx.id
+}
+```
+
+The function takes as parameters the TXID of the deployed smart contract to [create an instance](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#create-a-smart-contract-instance-from-a-transaction), along with the output index (which is usually 0). It uses the [`DefaultProvider`](../reference/classes/DefaultProvider) to fetch the transaction data from the blockchain. Subsequently, it reconstructs the smart contract instance using the [`fromTx`](../how-to-write-a-contract/built-ins.md#fromtx) function.
+
+Let's encapsulate the entire process within a main function, designed to deploy the contract and increment its value five times:
+
+```ts
+async function main() {
+    await compileContract()
+    let lastTxId = await deploy()
+    for (let i = 0; i < 5; ++i) {
+        lastTxId = await callIncrementOnChain(lastTxId)
+    }
+}
+
+(async () => {
+    await main()
+})()
+```
+
+If we execute the code, we should get an output similar to the following:
+
+```ts
+Counter deployed: 1cd6eb4ff0a5bd83f06c60c5e9a5c113c6e44fd876096e4e94e04a80fee8c8ca, the count is: 100
+Counter incrementOnChain called: c5b8d8f37f5d9c089a73a321d58c3ae205087ba21c1e32ed09a1b2fbd4f65330, the count now is: 101
+Counter incrementOnChain called: c62bb0f187f81dfeb5b70eafe80d549d3b2c6219e16d9575639b4fbdffd1d391, the count now is: 102
+Counter incrementOnChain called: 9fb217b98324b633d8a0469d6a2478f522c1f40c0b6d806430efe5ae5457ca0e, the count now is: 103
+Counter incrementOnChain called: 2080ddecc7f7731fc6afd307a57c8b117227755bd7b82eb0bc7cd8b78417ad9a, the count now is: 104
+Counter incrementOnChain called: de43687fd386e92cd892c18600d473bc38d5adb0cc34bbda892b94c61b5d5eb8, the count now is: 105
+```
+
+## Conclusion
+
+Congratulations! You've now deployed AND interacted with a Bitcoin smart contract.
+You can see a complete test example in our [boilerplate repository](https://github.com/sCrypt-Inc/boilerplate/blob/master/tests/testnet/counterFromTx.ts).

deploy-cli.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 3
+---
+
+# Deploy Using CLI
+
+The `deploy` command allows you to deploy an instance of a smart contract to the blockchain. You can simply run the following command in the root of an `sCrypt` project:
+
+```sh
+scrypt deploy
+```
+
+or
+
+```sh
+scrypt d
+```
+
+By default, the CLI tool will run a script named `deploy.ts` located in the root of the project. You can also specify a different deployment script using the `--file` or `-f` option.
+
+```sh
+scrypt d -f myCustomDeploy.ts
+```
+
+If the project was created using sCrypt CLI, it will already have a `deploy.ts` file present (except for [library](../how-to-publish-a-contract.md) projects). If not, the `deploy` command will generate a sample `deploy.ts` file.
+
+Here's an example of such a deployment file:
+```ts
+import { Demoproject } from './src/contracts/demoproject'
+import { bsv, TestWallet, DefaultProvider, sha256, toByteString, } from 'scrypt-ts'
+
+import * as dotenv from 'dotenv'
+
+// Load the .env file
+dotenv.config()
+
+// Read the private key from the .env file.
+// The default private key inside the .env file is meant to be used for the Bitcoin testnet.
+// See https://scrypt.io/docs/bitcoin-basics/bsv/#private-keys
+const privateKey = bsv.PrivateKey.fromWIF(process.env.PRIVATE_KEY)
+
+// Prepare signer. 
+// See https://scrypt.io/docs/how-to-deploy-and-call-a-contract/#prepare-a-signer-and-provider
+const signer = new TestWallet(privateKey, new DefaultProvider())
+
+async function main() {
+    // Compile the smart contract.
+    await Demoproject.compile()
+
+    // The amount of satoshis locked in the smart contract:
+    const amount = 100
+
+    // Instantiate the smart contract and pass constructor parameters.
+    const instance = new Demoproject(
+        sha256(toByteString('hello world', true))
+    )
+
+    // Connect to a signer.
+    await instance.connect(signer)
+
+    // Contract deployment.
+    const deployTx = await instance.deploy(amount)
+    console.log('Demoproject contract deployed: ', deployTx.id)
+}
+
+main()
+```
+
+Upon a successful execution you should see an output like the following:
+
+```
+Demoproject contract deployed:  15b8055cfaf9554035f8d3b866f038a04e40b45e28109f1becfe4d0af9f743cd
+```
+
+You can take a look at the deployed smart contract using the [WhatsOnChain block explorer](https://test.whatsonchain.com/tx/15b8055cfaf9554035f8d3b866f038a04e40b45e28109f1becfe4d0af9f743cd). 
+In our example, the first output contains the compiled smart contract code. 
+It is indexed using the hash (double SHA-256) of the script: [eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def](https://test.whatsonchain.com/script/eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def)

escrow.md

@@ -0,0 +1,178 @@
+---
+sidebar_position: 7
+---
+
+# Tutorial 7: Escrow
+
+## Overview
+
+In this tutorial, we will go over how to create and escrow smart contract with some advanced features, such as a requirement for multiple arbiters and a deadline, after which the buyer can get a refund.
+
+### What is an escrow smart contract?
+
+An escrow smart contract is a type of digital agreement that Bitcoin to facilitate transactions between parties in a secure, trustless manner. 
+
+In traditional escrow services, a trusted third party holds assets—like money, property, or goods—on behalf of the transacting parties. The assets are released only when specific conditions are met.
+
+In the case of an escrow smart contract, the "third party" is the smart contract itself, programmed on the blockchain. The contract is written with the conditions of the transaction, and if they are met, the contract can be unlocked and the recipient(s) get payed.
+
+### Our implementation
+
+We will implement a specific type of escrow, called a multi-sig escrow. The participants of this contract are a buyer (Alice), a seller (Bob) and one or more arbiters.
+
+Suppose Alice want's to buy a specific item from Bob. They don't trust each other, so they decide to use an escrow smart contract. They pick one or more arbiters, which they both trust. The job of the chosen arbiters is to verify, that the item really gets delivered in the right condition. If the conditions are met, the contract will pay the seller, Bob. In the opposite case, Alice gets a refund. Additionally, Alice is also eligible for a refund after a set period of time in the case the arbiters are not responsive.
+
+## Contract properties
+
+Let's declare the properties of our smart contract:
+
+```ts
+// Number of arbiters chosen.
+static readonly N_ARBITERS = 3
+
+// Buyer (Alice) address.
+@prop()
+readonly buyerAddr: PubKeyHash
+
+// Seller (Bob) address.
+@prop()
+readonly sellerAddr: PubKeyHash
+
+// Arbiter public keys.
+@prop()
+readonly arbiters: FixedArray<PubKey, typeof MultiSigEscrow.N_ARBITERS>
+
+// Contract deadline nLocktime value.
+// Either timestamp or block height.
+@prop()
+readonly deadline: bigint
+```
+
+## Public method - `confirmPayment`
+
+The first method of our contract will be `confirmPayment`. This public method will be called if the item was successfully delivered in the right condition.
+
+The method takes as inputs the buyers signature, along with her public key and the signatures of the arbiters.
+
+```ts
+// Buyer and arbiters confirm, that the item was delivered.
+// Seller gets paid.
+@method(SigHash.ANYONECANPAY_SINGLE)
+public confirmPayment(
+    buyerSig: Sig,
+    buyerPubKey: PubKey,
+    arbiterSigs: FixedArray<Sig, typeof MultiSigEscrow.N_ARBITERS>
+) {
+    // Validate buyer sig.
+    assert(
+        hash160(buyerPubKey) == this.buyerAddr,
+        'invalid public key for buyer'
+    )
+    assert(
+        this.checkSig(buyerSig, buyerPubKey),
+        'buyer signature check failed'
+    )
+
+    // Validate arbiter sigs.
+    assert(
+        this.checkMultiSig(arbiterSigs, this.arbiters),
+        'arbiters checkMultiSig failed'
+    )
+
+    // Ensure seller gets payed.
+    const amount = this.ctx.utxo.value
+    const out = Utils.buildPublicKeyHashOutput(this.sellerAddr, amount)
+    assert(hash256(out) == this.ctx.hashOutputs, 'hashOutputs mismatch')
+}
+```
+
+The method validates all signatures are correct and ensures the **seller** receives the funds.
+
+## Public method - `refund`
+
+Next, we implement the public method `refund`. If the delivery wasn't successful or there is something wrong with the item and needs to be sent back, the buyer is eligible for a refund.
+
+The method again takes as inputs the buyers signature, along with her public key and the signatures of the arbiters.
+
+```ts
+// Regular refund. Needs arbiters agreement.
+@method()
+public refund(
+    buyerSig: Sig,
+    buyerPubKey: PubKey,
+    arbiterSigs: FixedArray<Sig, typeof MultiSigEscrow.N_ARBITERS>
+) {
+    // Validate buyer sig.
+    assert(
+        hash160(buyerPubKey) == this.buyerAddr,
+        'invalid public key for buyer'
+    )
+    assert(
+        this.checkSig(buyerSig, buyerPubKey),
+        'buyer signature check failed'
+    )
+
+    // Validate arbiter sigs.
+    assert(
+        this.checkMultiSig(arbiterSigs, this.arbiters),
+        'arbiters checkMultiSig failed'
+    )
+
+    // Ensure buyer gets refund.
+    const amount = this.ctx.utxo.value
+    const out = Utils.buildPublicKeyHashOutput(this.buyerAddr, amount)
+    assert(hash256(out) == this.ctx.hashOutputs, 'hashOutputs mismatch')
+}
+```
+
+The method validates all signatures are correct and ensures the **buyer** receives the refund.
+
+## Public method - `refundDeadline`
+
+Lastly, we implement the `refundDeadline` method. This method can be called, after the specified contract deadline has been reached. After the deadline, the buyer can receive the refund, even without the arbiters agreement.
+
+The method takes as inputs in the buyers signature, along with her public key.
+
+```ts
+// Deadline for delivery. If reached, the  buyer gets refunded.
+@method()
+public refundDeadline(buyerSig: Sig, buyerPubKey: PubKey) {
+    assert(
+        hash160(buyerPubKey) == this.buyerAddr,
+        'invalid public key for buyer'
+    )
+    assert(
+        this.checkSig(buyerSig, buyerPubKey),
+        'buyer signature check failed'
+    )
+
+    // Require nLocktime enabled https://wiki.bitcoinsv.io/index.php/NLocktime_and_nSequence
+    assert(
+        this.ctx.sequence < UINT_MAX,
+        'require nLocktime enabled'
+    )
+
+    // Check if using block height.
+    if (this.deadline < LOCKTIME_BLOCK_HEIGHT_MARKER) {
+        // Enforce nLocktime field to also use block height.
+        assert(
+            this.ctx.locktime < LOCKTIME_BLOCK_HEIGHT_MARKER
+        )
+    }
+    assert(this.ctx.locktime >= this.deadline, 'deadline not yet reached')
+
+    // Ensure buyer gets refund.
+    const amount = this.ctx.utxo.value
+    const out = Utils.buildPublicKeyHashOutput(this.buyerAddr, amount)
+    assert(hash256(out) == this.ctx.hashOutputs, 'hashOutputs mismatch')
+}
+```
+
+The method checks the buyers signature validity. It also checks the transaction nLocktime value, to ensure it can be accepted by miners only after the deadline.
+
+## Conclusion
+
+Congratulations! You have completed the escrow tutorial!
+
+The full code along with [tests](https://github.com/sCrypt-Inc/boilerplate/blob/master/tests/local/multisigEscrow.test.ts) can be found in sCrypt's [boilerplate repository](https://github.com/sCrypt-Inc/boilerplate/blob/master/src/contracts/multisigEscrow.ts).
+

ethereum-devs.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 12
+---
+
+# sCrypt for Ethereum Developers
+
+# Smart contracts on Bitcoin vs Ethereum
+Bitcoin and Ethereum are both layer-1 blockchains with [fully programmable smart contracts](https://xiaohuiliu.medium.com/turing-machine-on-bitcoin-7f0ebe0d52b1).
+However, their designs fundamentally differ. 
+
+Ethereum is a global state machine, whose state consists of all smart contracts deployed on it. Each transaction is an input to the state machine, transitioning it to the next state according to the rules defined in the smart contract the transaction calls. The design imposes severe limitations on scalability, since transactions must be sequentially processed due to potential race conditions.
+
+In Bitcoin, transaction processing is independent of each other since all information needed is localized. There is no shared global state. Bitcoin is maximally parallelizable by design.
+
+Detailed side-by-side comparison can be found [here](ttps://xiaohuiliu.medium.com/bitcoin-vs-ethereum-smart-contracts-921e0a12b043), which is concisely summarized below.
+
+|| Ethereum | Bitcoin |
+|---|---|---|
+| Execution Environment | [Ethereum Virtual Machine](https://ethereum.org/en/developers/docs/evm/) (EVM) | [Bitcoin Virtual Machine](https://xiaohuiliu.medium.com/introduction-to-bitcoin-smart-contracts-9c0ea37dc757) (BVM)|
+| Model | Account | [UTXO](./overview.md#how-do-bitcoin-smart-contracts-work) |
+| Transaction Fee | $1-10 | $0.00001 |
+| Transactions Per Second | 15 | 3000+ |
+| Transaction Processing | Sequential | Parallel |
+| Scalability | Vertical | Horizontal |
+| Paradigm | Impure | Pure |
+
+
+# Smart contract development on Bitcoin vs Ethereum
+
+Besides unboundedly scalable fundation, Bitcoin also offers superior smart cotnract developer experience.
+
+The table below shows a comparison of popular Ethereum development tools and their counterparts in the Bitcoin ecosystem.
+
+There are two noticeable differences.
+1. Bitcoin smart contract is written in TypeScript, one of the most popular programming languages tens of millions of Web2 developers are already familiar with. They do not have to learn a new niche programming language like Solidity, placing a high barrier to entry. They can reuse all of their favoriate tools, such as Visual Studio Code, [WebStorm](https://www.jetbrains.com/webstorm/), and NPM. 
+2. Ethereum's development tools are **fragmented**. They are developed by different entities, who are often competitors. There is disincentive to make them more interoperable, thus they don't communicate with each other well. By contrast, sCrypt takes a more holistic and systematic approach. It builds a unified full-stack platform that encompasses most tools, from programming language, to framework/libraries. Developed synergistically, they are fully compatible with each other, greatly simplifing and streamlining development process.
+
+
+|| Ethereum | Bitcoin |
+|---|---|---|
+| Programming Language | [Solidity](https://soliditylang.org/) | [sCrypt DSL](https://docs.scrypt.io/) |
+| Framework | [Hardhat](https://hardhat.org/) / [Truffle](https://trufflesuite.com/truffle/) | [The sCrypt CLI](https://www.npmjs.com/package/scrypt-cli) |
+| Libraries | [Web3.js](https://web3js.org/#/) / [Ethers.js](https://docs.ethers.org) | [scrypt-ts](https://docs.scrypt.io/how-to-write-a-contract/) |
+| Developer Platform | [Alchemy](https://www.alchemy.com/) / [Infura](https://www.infura.io/) | [sCrypt](https://scrypt.io) |
+| IDE | [Remix](https://remix.ethereum.org)[^1] | [Visual Studio Code](https://code.visualstudio.com/) |
+| Wallet | [MetaMask](https://metamask.io/) | [Sensilet](https://sensilet.com/) |
+| Block Explorer | [Etherscan](https://etherscan.io/) | [WhatsOnChain](https://whatsonchain.com/) |
+
+[^1]: Visual Studio Code can also be used for Solidity with various extentions. However, its support is extremely limited compared to that of sCrypt, a TypeScript DSL, which is supported out of box without any extension. For example, [VS Code debugger](./how-to-debug-a-contract.md) has first-class comprehensive support for sCrypt, but does not suppport Solidity.
+
+## Example Code
+
+Let's compare a counter smart contract between Solidity and sCrypt.
+
+```js
+pragma solidity >=0.7.0 <0.9.0;
+
+contract Counter {
+
+    int private count;
+
+    constructor(int _initialCount) {
+        count = _initialCount;
+    }
+
+    function incrementCounter() public {
+        count += 1;
+    }
+
+    function getCount() public view returns (int) {
+        return count;
+    }
+
+}
+```
+
+```ts
+class Counter extends SmartContract {
+
+    @prop(true)
+    count: bigint
+
+    constructor(count: bigint) {
+        super(...arguments)
+        this.count = count
+    }
+
+    @method()
+    public incremenCounter() {
+        this.count++
+
+        assert(hash256(this.buildStateOutput(this.ctx.utxo.value)) == this.ctx.hashOutputs)
+    }
+
+}
+```

faq.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 15
+---
+
+# FAQ
+
+## Broadcast double-spending transactions
+
+You would mainly get two different errors when broadcasting a double-spending transaction, depending on the status of the transaction you're trying to double-spend.
+
+- If the transaction you're trying to double-spend is still unconfirmed and in the mempool, the error would be `txn-mempool-conflict`.
+
+![](../static/img/txn-mempool-conflict.png)
+
+- If the transaction you're trying to double-spend is already confirmed, the error would be `Missing inputs`.
+
+![](../static/img/missing-inputs.png)
+
+If you encounter these errors when interacting with the dApp, it is mainly because the state of the contract has changed, but your browser has not been updated in time, such as the contract has been called by another user. At this time, it is equivalent to that you are interacting with the contract instance that is not in the latest state, resulting in a double-spending.
+
+To fix this issue, you generally only need to wait for a few seconds, the browser will automatically obtain the latest contract instance after receiving the contract state-change event, or manually refresh the browser yourself, and then try again.
+
+If you encounter these errors when running the testnet cases, it is mainly because the provider failed to update your UTXO in time so they returned UTXOs that have already been spent when you request. Using these UTXOs that have been spent to build transactions will result in a double-spending. This situation is not common, it might be because there are too many transactions on the blockchain network at this time, the provider cannot update UTXO timely, or somehow the provider's server load is heavy. 
+
+To fix this issue, you generally only need to wait a few seconds and re-run the test. If it still can't be solved, you can also increase the time gap between sending transactions, for example, add a `sleep` ahead of requesting the UTXO after sending transactions, so that the provider has enough time to update the UTXO.
+
+## Input string too short
+
+If you do not set the `PRIVATE_KEY` environment variable in `.env` file before deploying a contract, you would get an `Input string too short` error.
+
+![](../static/img/no-private-key.png)
+
+Please follow [this guide](./how-to-deploy-and-call-a-contract/faucet.md) to generate a new private key or export the private key from your Sensilet wallet, then fund the private key's address with our [faucet](https://scrypt.io/faucet/).
+
+## No sufficient utxos
+
+If you don't fund your private key's address before deploying a contract, you would get a `No sufficient utxos` error.
+
+![](../static/img/insufficient-balance.png)
+
+Please fund your address with our [faucet](https://scrypt.io/faucet/) first.

faucet.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 4
+---
+
+# Faucet
+
+It is highly recommended to test your contract on the [testnet](https://test.whatsonchain.com/) after passing local tests. It ensures that a contract can be successfully deployed and invoked as expected on the blockchain.
+
+Before deploy and call a contract, you need to have a funded address:
+
+1. Generate a private key with the following command, after creating a project:
+
+```sh
+scrypt project demo
+cd demo
+npm install
+npm run genprivkey
+```
+
+The command will generate a private key and store it in a `.env` file in our project's root directory. It also outputs the [Bitcoin address](https://wiki.bitcoinsv.io/index.php/Bitcoin_address) corresponding to our private key.
+
+2. Fund the private key's address with some testnet coins. You could use this [faucet](https://scrypt.io/faucet) to receive test coins.
+
+![faucet](../../static/img/faucet.gif)
+
+### Use the Sensilet Wallet
+
+Alternatively, if you have already installed [Sensilet](https://sensilet.com/), you can extract and use its private key on testnet as follows.
+
+![](../../static/img/extract-sensilet-private-key.gif)

hello-world.md

@@ -0,0 +1,123 @@
+---
+sidebar_position: 1
+---
+
+# Tutorial 1: Hello World
+
+
+## Overview
+In this tutorial, we will go over how to quickly create a “Hello World” smart contract, deploy and call it.
+
+## Create a new project
+
+Make sure [all prerequisite tools](../../installation) are installed.
+
+Run the following commands to create a new project:
+
+```sh
+scrypt project helloworld
+cd helloworld
+npm install
+```
+
+The resulting project will contain a sample smart contract `src/contracts/helloworld.ts`, along with all the scaffolding. Let's modify it to the following code:
+
+
+```ts
+import { assert, ByteString, method, prop, sha256, Sha256, SmartContract } from 'scrypt-ts'
+
+export class Helloworld extends SmartContract {
+
+    @prop()
+    hash: Sha256;
+
+    constructor(hash: Sha256){
+        super(...arguments);
+        this.hash = hash;
+    }
+
+    @method()
+    public unlock(message: ByteString) {
+        assert(sha256(message) == this.hash, 'Hash does not match')
+    }
+}
+```
+
+The `Helloworld` contract stores the sha256 hash of a message in the contract property `hash`. Only a message which hashes to the value set in `this.hash` will unlock the contract.
+
+Now let’s look at what is in the smart contract.
+
+
+- `SmartContract`: all smart contracts must extend the `SmartContract` base class.
+
+- `@prop`:  the [`@prop` decorator](../how-to-write-a-contract/how-to-write-a-contract.md#properties) marks a contract property.
+
+- `@method`: the [`@method` decorator](../how-to-write-a-contract/how-to-write-a-contract.md#method-decorator) marks a contract method. A [public method](../how-to-write-a-contract/#public-methods) is an entry point to a contract.
+
+- `assert`: throws an error and makes the method call fail if its first argument is `false`. Here it ensures the passed message hashed to the expected digest.
+
+
+## Contract Deployment & Call
+
+Before we deploy the contract, follow [the instruction](../../how-to-deploy-and-call-a-contract/faucet) to fund a Bitcoin key.
+
+1. To [deploy a smart contract](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-deployment), simply call its `deploy` method.
+
+2. To [call a smart contract](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call), call one of its public method.
+
+Overwrite `deploy.ts` in the root of the project with the following code to deploy and call the `Helloworld` contract:
+
+```ts
+import { Helloworld } from './src/contracts/helloworld'
+import { getDefaultSigner } from './tests/utils/txHelper'
+import { toByteString, sha256 } from 'scrypt-ts'
+
+(async () => {
+
+    const message = toByteString('hello world', true)
+
+    await Helloworld.compile()
+    const instance = new Helloworld(sha256(message))
+
+    // connect to a signer
+    await instance.connect(getDefaultSigner())
+
+    // deploy the contract and lock up 42 satoshis in it
+    const deployTx = await instance.deploy(42)
+    console.log('Helloworld contract deployed: ', deployTx.id)
+
+    // contract call
+    const { tx: callTx } = await instance.methods.unlock(message)
+    console.log('Helloworld contract `unlock` called: ', callTx.id)
+
+})()
+```
+
+Run the following command:
+```
+npx ts-node deploy.ts
+```
+You will see some output like:
+
+![](../../static/img/hello-world-deploy-and-call-output.png)
+
+
+You can view [the deployment transaction](https://test.whatsonchain.com/tx/b10744292358eda2cfae3baae5cd486e30136b086011f7953aed9098f62f4245) using the WhatsOnChain blockchain explorer:
+
+![](../../static/img/hello-world-contract-deploy-tx.png)
+
+
+You can also view [the calling transaction](https://test.whatsonchain.com/tx/f28175616b6dd0ebe2aad41505aabb5bf2864e2e6d1157168183f51b6194d3e6):
+
+![](../../static/img/hello-world-contract-call-tx.png)
+
+Congrats! You have deployed and called your first Bitcoin smart contract.
+
+
+
+
+
+
+
+
+

how-to-add-a-provider.md

@@ -0,0 +1,301 @@
+---
+sidebar_position: 1
+---
+
+# How to Add a Provider
+
+
+In the [contract testing section](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#provider), we learned about the Provider class in sCrypt. This class serves as an abstraction of a Bitcoin node, allowing your application to communicate with the Bitcoin network.
+
+`sCrypt` provides the following providers by default:
+
+* `DummyProvider`: A mockup provider intended for local testing. It does not connect to the Bitcoin blockchain and thus cannot send transactions.
+
+* `DefaultProvider`: The default provider is the safest and easiest way to begin developing on Bitcoin, and is also robust enough for use in production. It can be used in testnet as well as mainnet.
+
+* For a full list of providers, see [here](../reference/classes/Provider.md#hierarchy).
+
+## Implementation
+
+### Base Class `Provider`
+
+To implement your own provider, you must extend the base class `Provider`. Here's the definition of this class:
+
+```ts
+/**
+ * A Provider is an abstraction of non-account-based operations on a blockchain and is generally not directly involved in signing transaction or data.
+ */
+export abstract class Provider extends EventEmitter  {
+
+  constructor() {
+    super()
+    this._isProvider = true;
+  }
+
+  /**
+   * check if provider is ready
+   */
+  abstract isConnected(): boolean;
+
+  /**
+   * Implement the connection provider, for example, verify the api key during the connection process.
+   * @returns a connected provider. Throw an exception if the connection fails.
+   */
+  abstract connect(): Promise<this>;
+
+  /**
+   * update provider network
+   * @param network  Network type to be updated
+   */
+  abstract updateNetwork(network: bsv.Networks.Network): Promise<boolean>;
+
+  /**
+   * @returns The network this provider is connected to.
+   */
+  abstract getNetwork(): Promise<bsv.Networks.Network>;
+
+  /**
+   * @returns The fee rate for sending transactions through this provider.
+   */
+  abstract getFeePerKb(): Promise<number>;
+
+  /**
+ * Get a best guess of the fee for a transaction.
+ * @param tx A transaction object to estimate.
+ * @returns The estimated fee in satoshis.
+ */
+  async getEstimateFee(tx: bsv.Transaction): Promise<number> {
+    const copy = new bsv.Transaction(tx.uncheckedSerialize());
+    // use a copy bcoz `feePerKb` resets all the signatures for inputs.
+    copy.feePerKb(await this.getFeePerKb());
+    return copy.getEstimateFee();
+  }
+
+  // Executions
+
+  /**
+   * Send a raw transaction hex string.
+   * @param rawTxHex The raw transaction hex string to send.
+   * @returns A promise which resolves to the hash of the transaction that has been sent.
+   */
+  abstract sendRawTransaction(rawTxHex: string): Promise<TxHash>;
+
+  /**
+   * Send a transaction object.
+   * @param tx The transaction object to send.
+   * @returns A promise which resolves to the hash of the transaction that has been sent. 
+   * @throws If there is a problem with the `tx` object during serialization.
+   */
+  sendTransaction(tx: bsv.Transaction): Promise<TxHash> {
+    // TODO: fix tx.serialize issue 
+    return this.sendRawTransaction(tx.serialize({ disableIsFullySigned: true }));
+  }
+
+  // Queries
+
+  /**
+   * Get a transaction from the network.
+   * @param txHash The hash value of the transaction.
+   * @returns The query result with the transaction information.
+   */
+  abstract getTransaction(txHash: TxHash): Promise<TransactionResponse>
+
+  /**
+   * Get a list of the P2PKH UTXOs.
+   * @param address The address of the returned UTXOs belongs to.
+   * @param options The optional query conditions, see details in `UtxoQueryOptions`. 
+   * @returns  A promise which resolves to a list of UTXO for the query options.
+   */
+  abstract listUnspent(address: AddressOption, options?: UtxoQueryOptions): Promise<UTXO[]>;
+
+  /**
+   * Get the balance of BSVs in satoshis for an address.
+   * @param address The query address.
+   * @returns A promise which resolves to the address balance status.
+   */
+  abstract getBalance(address: AddressOption): Promise<{ confirmed: number, unconfirmed: number }>;
+
+  /**
+   * Get a list of UTXO for a certain contract instance.
+   * @param genesisTxHash The hash value of deployment transaction of the contract instance.
+   * @param outputIndex The output index of the deployment transaction of the contract instance.
+   * @returns A promise which resolves to a list of transaction UTXO.
+   */
+  abstract getContractUTXOs(genesisTxHash: TxHash, outputIndex: number): Promise<UTXO[]>;
+
+  // Inspection
+
+  readonly _isProvider: boolean;
+
+  /**
+   * Check if an object is a `Provider`
+   * @param value The target object
+   * @returns Returns `true` if and only if `object` is a Provider.
+   */
+  static isProvider(value: any): value is Provider {
+    return !!(value && value._isProvider);
+  }
+}
+```
+
+It is recommended that your provider implements all `abstract` methods. For non-`abstract` methods, the default implementation is usually sufficient.
+
+
+### `Example: WhatsonchainProvider`
+
+Let's walk through the process of implementing our own provider. In this example we'll implement a provider for [WhatsOnChain](https://whatsonchain.com) (WoC).
+
+
+1. First let's implement the `isConnected()` and `connect()` functions. Because WoC doesn't need to maintan an open connection, not does it require any authentication by default, it's simply marked as connected by default. If your chosen provider does, here's probably the place to implement the connection logic.
+
+```ts
+isConnected(): boolean {
+  return true;
+}
+
+override async connect(): Promise<this> {
+  this.emit(ProviderEvent.Connected, true);
+  return Promise.resolve(this);
+}
+```
+
+2. Next, we'll implement the network functions. Here, your providers selected network can be toggled. WoC supports both the Bitcoin mainnet along with testnet, so we don't do further checking:
+
+```ts
+override async updateNetwork(network: bsv.Networks.Network): Promise<boolean> {
+  this._network = network;
+  this.emit(ProviderEvent.NetworkChange, network);
+  return Promise.resolve(true);
+}
+
+override async getNetwork(): Promise<bsv.Networks.Network> {
+  return Promise.resolve(this._network);
+}
+```
+
+If your provider is only meant for the testnet, you could do something like this:
+```ts
+override async updateNetwork(network: bsv.Networks.Network): Promise<boolean> {
+  if (network != bsv.Networks.testnet) {
+    throw new Error('Network not supported.')
+  }
+  this._network = network;
+  this.emit(ProviderEvent.NetworkChange, network);
+  return Promise.resolve(true);
+}
+```
+
+3. Now let's set the transaction fee rate. In our example, we hard-code the value to be 50 satoshis per Kb:
+
+```ts
+override async getFeePerKb(): Promise<number> {
+  return Promise.resolve(50);
+}
+```
+
+4. Let's implement the function that will send the transaction data to our provider:
+
+```ts
+override async sendRawTransaction(rawTxHex: string): Promise<TxHash> {
+  // 1 second per KB
+  const size = Math.max(1, rawTxHex.length / 2 / 1024); //KB
+  const timeout = Math.max(10000, 1000 * size);
+  try {
+    const res = await superagent.post(
+      `${this.apiPrefix}/tx/raw`
+    )
+      .timeout({
+        response: timeout,  // Wait 5 seconds for the server to start sending,
+        deadline: 60000, // but allow 1 minute for the file to finish loading.
+      })
+      .set('Content-Type', 'application/json')
+      .send({ txhex: rawTxHex })
+    return res.body;
+  } catch (error) {
+    if (error.response && error.response.text) {
+      throw new Error(`WhatsonchainProvider ERROR: ${error.response.text}`)
+    }
+    throw new Error(`WhatsonchainProvider ERROR: ${error.message}`)
+  }
+}
+```
+
+In the function we use the [`superagent`](https://www.npmjs.com/package/superagent) to send requests to WoC's HTTP endpoint. Check out their [docs](https://docs.taal.com/core-products/whatsonchain) for a description of the endpoints they provide.
+
+5. Now we need to implement some queries. First let's implement the function to get a list of [UTXO's](https://wiki.bitcoinsv.io/index.php/UTXO) for a certain address:
+
+```ts
+override async listUnspent(
+    address: AddressOption, 
+    options?: UtxoQueryOptions
+    ): Promise<UTXO[]> {
+
+  const res = await superagent.get(`${this.apiPrefix}/address/${address}/unspent`);
+  const utxos: UTXO[] =
+    res.body.map(item => ({
+      txId: item.tx_hash,
+      outputIndex: item.tx_pos,
+      satoshis: item.value,
+      script: bsv.Script.buildPublicKeyHashOut(address).toHex(),
+    }));
+
+  if (options?.minSatoshis && utxos.reduce((s, u) => s + u.satoshis, 0) < options.minSatoshis) {
+    throw new Error(`WhatsonchainProvider ERROR: not enough utxos for the request amount of ${options.minSatoshis} on address ${address.toString()}`);
+  }
+
+  return utxos;
+}
+```
+
+Next, we'll make the `getBalance` function parse out the addresses balance from the UTXO's:
+
+```ts
+override async getBalance(
+    address?: AddressOption
+    ): Promise<{ confirmed: number, unconfirmed: number }> {
+
+  return this.listUnspent(address, { minSatoshis: 0 }).then(utxos => {
+    return {
+      confirmed: utxos.reduce((acc, utxo) => {
+        acc += utxo.satoshis;
+        return acc;
+      }, 0),
+      unconfirmed: 0
+    }
+  })
+
+}
+```
+
+We also implement the function to query the raw transaction using the transactions ID:
+```ts
+override async getTransaction(txHash: string): Promise<TransactionResponse> {
+  try {
+    const res = await superagent.get(`${this.apiPrefix}/tx/${txHash}/hex`);
+    return new bsv.Transaction(res.text)
+  } catch (e) {
+    throw new Error(`WhatsonchainProvider ERROR: failed fetching raw transaction data: ${e.message}`);
+  }
+}
+```
+
+
+Lastly, if our provider doesn't support a certain query, we can simply throw an error by default:
+```ts
+override async getContractUTXOs(genesisTxHash: string, outputIndex?: number): Promise<UTXO[]> {
+    throw new Error("Method #getContractUTXOs not implemented in WhatsonchainProvider.");
+  }
+```
+
+## Using the Provider
+
+Providers are usually used by a `Signer`:
+
+```ts
+const provider = new WhatsonchainProvider(bsv.Networks.mainnet)
+const signer = new TestWallet(privateKey, provider)
+
+await contractInstance.connect(signer);
+```
+
+Here, the signer will use our `WhatsonchainProvider` for each Bitcoin network operation it needs. The next section describes signers and how we can implement a custom one.

how-to-add-a-signer.md

@@ -0,0 +1,430 @@
+---
+sidebar_position: 2
+---
+
+# How to Add a Signer
+
+
+As described in [this section](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#provider), a signer is an abstraction of private keys, which can be used to sign messages and transactions. A simple signer would be a single private key, while a complex signer is a wallet.
+
+`sCrypt` provides the following signers by default:
+
+1. `TestWallet` : a simple wallet that can hold multiple private keys, with in-memory utxo management. Should only be used for testing.
+2. `SensiletSigner`: a signer powered by the popular smart contract wallet [Sensilet](https://sensilet.com/). Can be used in production.
+
+## Implementation
+
+### Base Class `Signer`
+
+If you want to implement your own signer, you must inherit from the base class `Signer`.
+
+
+```ts
+/**
+ * A `Signer` is a class which in some way directly or indirectly has access to a private key, which can sign messages and transactions to authorize the network to perform operations.
+ */
+export abstract class Signer {
+
+  provider?: Provider;
+  readonly _isSigner: boolean;
+
+  constructor(provider?: Provider) {
+    this._isSigner = true;
+    this.provider = provider;
+  }
+
+  /**
+   * Connect a provider to `this`.
+   * @param provider The target provider.
+   * @returns 
+   */
+  abstract connect(provider: Provider): Promise<this>;
+
+  // Account
+
+  /**
+   * 
+   * @returns A promise which resolves to the address to the default private key of the signer.
+   */
+  abstract getDefaultAddress(): Promise<bsv.Address>;
+
+  /**
+   * 
+   * @returns A promise which resolves to the public key of the default private key of the signer.
+   */
+  abstract getDefaultPubKey(): Promise<bsv.PublicKey>;
+
+  /**
+   * 
+   * @param address The request address, using the default address if omitted.
+   * @returns The public key result.
+   * @throws If the private key for the address does not belong this signer.
+   */
+  abstract getPubKey(address?: AddressOption): Promise<bsv.PublicKey>;
+
+  // Signing
+
+  /**
+   * Sign a raw transaction hex string.
+   * 
+   * @param rawTxHex The raw transaction hex to sign.
+   * @param options The options for signing, see the details of `SignTransactionOptions`.
+   * @returns A promise which resolves to the signed transaction hex string.
+   * @throws If any input of the transaction can not be signed properly.
+   */
+  abstract signRawTransaction(rawTxHex: string, options: SignTransactionOptions): Promise<string>;
+
+  /**
+   * Sign a transaction object.
+   * @param tx The transaction object to sign.
+   * @param options The options for signing, see the details of `SignTransactionOptions`.
+   * @returns A promise which resolves to the signed transaction object.
+   */
+  abstract signTransaction(tx: bsv.Transaction, options?: SignTransactionOptions): Promise<bsv.Transaction>;
+
+  /**
+   * Sign a message string.
+   * @param message The message to be signed.
+   * @param address The optional address whose private key will be used to sign `message`, using the default private key if omitted.
+   * @returns A promise which resolves to the signautre of the message. 
+   */
+  abstract signMessage(message: string, address?: AddressOption): Promise<string>;
+
+  /**
+   * Get the requested transaction signatures for the raw transaction.
+   * @param rawTxHex The raw transaction hex to get signatures from.
+   * @param sigRequests The signature requst informations, see details in `SignatureRequest`.
+   * @returns A promise which resolves to a list of `SignatureReponse` corresponding to `sigRequests`.
+   */
+  abstract getSignatures(rawTxHex: string, sigRequests: SignatureRequest[]): Promise<SignatureResponse[]>;
+
+  /**
+   * Get the connected provider.
+   * @returns the connected provider.
+   * @throws if no provider is connected to `this`.
+   */
+  get connectedProvider(): Provider {
+    if (!this.provider) {
+      throw new Error(`the provider of singer ${this.constructor.name} is not set yet!`);
+    }
+    if (!this.provider.isConnected()) {
+      throw new Error(`the provider of singer ${this.constructor.name} is not connected yet!`);
+    }
+
+    return this.provider;
+  }
+
+  /**
+   * Sign the transaction, then broadcast the transaction
+   * @param tx A transaction is signed and broadcast
+   * @param options The options for signing, see the details of `SignTransactionOptions`.
+   * @returns A promise which resolves to the transaction id.
+   */
+  async signAndsendTransaction(tx: bsv.Transaction, options?: SignTransactionOptions): Promise<TransactionResponse> {
+    await tx.sealAsync();
+    const signedTx = await this.signTransaction(tx, options);
+    await this.connectedProvider.sendTransaction(signedTx);
+    return signedTx;
+  };
+
+  /**
+   * Get a list of the P2PKH UTXOs.
+   * @param address The address of the returned UTXOs belongs to.
+   * @param options The optional query conditions, see details in `UtxoQueryOptions`. 
+   * @returns  A promise which resolves to a list of UTXO for the query options.
+   */
+  listUnspent(address: AddressOption, options?: UtxoQueryOptions): Promise<UTXO[]> {
+    // default implemention using provider, can be overrided.
+    return this.connectedProvider.listUnspent(address, options);
+  }
+
+  /**
+   * Get the balance of BSVs in satoshis for an address.
+   * @param address The query address.
+   * @returns A promise which resolves to the address balance status.
+   */
+  getBalance(address?: AddressOption): Promise<{ confirmed: number, unconfirmed: number }> {
+    // default implemention using provider, can be overrided.
+    return this.connectedProvider.getBalance(address);
+  }
+
+  // Inspection
+  /**
+   * Check if an object is a `Signer`
+   * @param value The target object
+   * @returns Returns `true` if and only if `object` is a Provider.
+   */
+  static isSigner(value: any): value is Signer {
+    return !!(value && value._isSigner);
+  }
+
+}
+```
+
+It is recommended that your signer implements all `abstract` methods. For non-`abstract` methods, the default implementation is usually sufficient.
+
+
+### `Example: SensiletSigner`
+
+Next, we use the [Sensilet wallet](https://sensilet.com/) as an example to show how to implement a `SensiletSigner`.
+
+
+1. In the `connect` method, you usually attempt to connect to a provider and save it:
+
+```ts
+override async connect(provider: Provider): Promise<this> {
+    // we should make sure sensilet is connected  before we connect a provider.
+    const isSensiletConnected = await this.isSensiletConnected();
+
+    if(!isSensiletConnected) {
+      Promise.reject(new Error('Sensilet is not connected!'))
+    }
+
+    if(!provider.isConnected()) {
+      // connect the provider
+      await provider.connect();
+    }
+
+    this.provider = provider;
+    return this;
+}
+```
+
+2. Returns the address to the default private key of the wallet in `getDefaultAddress`:
+
+```ts
+/**
+ * Get an object that can directly interact with the Sensilet wallet,
+ * if there is no connection with the wallet, it will request to establish a connection.
+ * @returns SensiletWalletAPI
+ */
+async getConnectedTarget(): Promise<SensiletWalletAPI> {
+
+    const isSensiletConnected = await this.isSensiletConnected();
+    if (!isSensiletConnected) {
+      // trigger connecting to sensilet account when it's not connected.
+      try {
+        const addr = await this._target.requestAccount();
+        this._address = bsv.Address.fromString(addr);
+      } catch (e) {
+        throw new Error('Sensilet requestAccount failed')
+      }
+    }
+    return this.getSensilet();
+}
+
+override async getDefaultAddress(): Promise<bsv.Address> {
+    // 
+    const sensilet = await this.getConnectedTarget();
+    const address = await sensilet.getAddress();
+    return bsv.Address.fromString(address);
+}
+```
+
+3. Returns the public key to the default private key of the wallet in `getDefaultPubKey`:
+
+```ts
+override async getDefaultPubKey(): Promise<PublicKey> {
+    const sensilet = await this.getConnectedTarget();
+    const pubKey = await sensilet.getPublicKey();
+    return Promise.resolve(new bsv.PublicKey(pubKey));
+}
+```
+
+4. Since Sensilet is a single-address wallet, we simply ignore the `getPubKey` method:
+
+```ts
+override async getPubKey(address: AddressOption): Promise<PublicKey> {
+    throw new Error(`Method ${this.constructor.name}#getPubKey not implemented.`);
+}
+```
+
+5. Both `signTransaction` and `signRawTransaction` sign the transaction, but their parameters are different. `signRawTransaction` converts the parameters and delegates the implementation of the signing to `signTransaction`.
+
+The following are types used in these two functions:
+
+
+```ts
+
+/** 
+ * `SignatureRequest` contains required informations for a signer to sign a certain input of a transaction.
+ */
+export interface SignatureRequest {
+  /** The index of input to sign. */
+  inputIndex: number;
+  /** The previous output satoshis value of the input to spend. */
+  satoshis: number;
+  /** The address(es) of corresponding private key(s) required to sign the input. */
+  address: AddressesOption;
+  /** The previous output script of input, default value is a P2PKH locking script for the `address` if omitted. */
+  scriptHex?: string;
+  /** The sighash type, default value is `SIGHASH_ALL | SIGHASH_FORKID` if omitted. */
+  sigHashType?: number;
+  /** The extra information for signing. */
+  data?: unknown;
+}
+
+/** 
+ * `SignatureResponse` contains the signing result corresponding to a `SignatureRequest`.
+ */
+export interface SignatureResponse {
+  /** The index of input. */
+  inputIndex: number;
+  /** The signature.*/
+  sig: string;
+  /** The public key bound with the `sig`. */
+  publicKey: string;
+  /** The sighash type, default value is `SIGHASH_ALL | SIGHASH_FORKID` if omitted. */
+  sigHashType: number;
+}
+
+/** 
+ * `SignTransactionOptions` is the options can be provided when signing a transaction.
+*/
+export interface SignTransactionOptions {
+  /** The `SignatureRequest` for the some inputs of the transaction. */
+  sigRequests?: SignatureRequest[];
+  /** The address(es) whose corresponding private key(s) should be used to sign the tx. */
+  address?: AddressesOption;
+}
+```
+
+`signTransaction` will convert the above parameter types to the parameter types required by the [sensilet api](https://doc.sensilet.com/guide/sensilet-api.html#signtx). And call the sensilet api to complete the signature, which is implemented in `getSignatures` function.
+
+```ts
+override async signRawTransaction(rawTxHex: string, options: SignTransactionOptions): Promise<string> {
+    // convert `rawTxHex` to a transation object
+    const sigReqsByInputIndex: Map<number, SignatureRequest> = (options?.sigRequests || []).reduce((m, sigReq) => { m.set(sigReq.inputIndex, sigReq); return m; }, new Map());
+    const tx = new bsv.Transaction(rawTxHex);
+    tx.inputs.forEach((_, inputIndex) => {
+      const sigReq = sigReqsByInputIndex.get(inputIndex);
+      if (!sigReq) {
+        throw new Error(`\`SignatureRequest\` info should be provided for the input ${inputIndex} to call #signRawTransaction`)
+      }
+      const script = sigReq.scriptHex ? new bsv.Script(sigReq.scriptHex) : bsv.Script.buildPublicKeyHashOut(sigReq.address.toString());
+      // set ref output of the input
+      tx.inputs[inputIndex].output = new bsv.Transaction.Output({
+        script,
+        satoshis: sigReq.satoshis
+      })
+    });
+
+    const signedTx = await this.signTransaction(tx, options);
+    return signedTx.toString();
+}
+
+override async signTransaction(tx: Transaction, options?: SignTransactionOptions): Promise<Transaction> {
+
+    const network = await this.getNetwork();
+    // Generate default `sigRequests` if not passed by user
+    const sigRequests: SignatureRequest[] = options?.sigRequests?.length ? options.sigRequests :
+
+      tx.inputs.map((input, inputIndex) => {
+        const useAddressToSign = options && options.address ? options.address :
+          input.output?.script.isPublicKeyHashOut()
+            ? input.output.script.toAddress(network)
+            : this._address;
+
+        return {
+          inputIndex,
+          satoshis: input.output?.satoshis,
+          address: useAddressToSign,
+          scriptHex: input.output?.script?.toHex(),
+          sigHashType: DEFAULT_SIGHASH_TYPE,
+        }
+      })
+
+    const sigResponses = await this.getSignatures(tx.toString(), sigRequests);
+
+    // Set the acquired signature as an unlocking script for the transaction
+    tx.inputs.forEach((input, inputIndex) => {
+      const sigResp = sigResponses.find(sigResp => sigResp.inputIndex === inputIndex);
+      if (sigResp && input.output?.script.isPublicKeyHashOut()) {
+        var unlockingScript = new bsv.Script("")
+        .add(Buffer.from(sigResp.sig, 'hex'))
+        .add(Buffer.from(sigResp.publicKey, 'hex'));
+        
+        input.setScript(unlockingScript)
+      }
+    })
+
+    return tx;
+}
+
+/**
+ * Get signatures with sensilet api
+ * @param rawTxHex a transation raw hex
+ * @param sigRequests a `SignatureRequest` array for the some inputs of the transaction.
+ * @returns a `SignatureResponse` array
+ */
+async getSignatures(rawTxHex: string, sigRequests: SignatureRequest[]): Promise<SignatureResponse[]> {
+    const network = await this.getNetwork()
+    // convert `sigRequests` to the parameter type required by sensilet `signTx` api
+    const inputInfos = sigRequests.flatMap((sigReq) => {
+      const addresses = parseAddresses(sigReq.address, network);
+      return addresses.map(address => {
+        return {
+          txHex: rawTxHex,
+          inputIndex: sigReq.inputIndex,
+          scriptHex: sigReq.scriptHex || bsv.Script.buildPublicKeyHashOut(address).toHex(),
+          satoshis: sigReq.satoshis,
+          sigtype: sigReq.sigHashType || DEFAULT_SIGHASH_TYPE,
+          address: address.toString()
+        }
+      });
+    });
+
+    const sensilet = await this.getConnectedTarget();
+    // call sensilet `signTx` api to sign transaction
+    // https://doc.sensilet.com/guide/sensilet-api.html#signtx
+    const sigResults = await sensilet.signTx({
+      list: inputInfos
+    });
+
+    return inputInfos.map((inputInfo, idx) => {
+      return {
+        inputIndex: inputInfo.inputIndex,
+        sig: sigResults.sigList[idx].sig,
+        publicKey: sigResults.sigList[idx].publicKey,
+        sigHashType: sigRequests[idx].sigHashType || DEFAULT_SIGHASH_TYPE
+      }
+    })
+}
+```
+
+6. Sensilet supports signing messages, if your wallet does not support it, you can throw an exception in the `signMessage` function:
+
+```ts
+override async signMessage(message: string, address?: AddressOption): Promise<string> {
+    if (address) {
+      throw new Error(`${this.constructor.name}#signMessge with \`address\` param is not supported!`);
+    }
+    const sensilet = await this.getConnectedTarget();
+    return sensilet.signMessage(message);
+}
+```
+
+So far, we have implemented all abstract methods. The remaining non-abstract methods can reuse the default implementation, that is, delegating to the connected [provider](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#provider). If you have a customized implementation, you can override them. For example, we can use the [Sensilet api `getBsvBalance`](https://doc.sensilet.com/guide/sensilet-api.html#getbsvbalance) to obtain the balance of an address.
+
+```ts
+override getBalance(address?: AddressOption): Promise<{ confirmed: number, unconfirmed: number }> {
+    if(address) {
+      return this.connectedProvider.getBalance(address);
+    }
+    return this.getConnectedTarget().then(target => target.getBsvBalance()).then(r => r.balance)
+}
+```
+
+Now we have implemented `SensiletSigner`. The full code is [here](https://gist.github.com/xhliu/73104028deaf95c8b6665bf96496fe11#file-sensiletsigner-ts-L44).
+
+## Use your signer
+
+Just connect your signer to a smart contract instance like any other signers:
+
+```ts
+// declare your signer
+const your_signer = new YourSigner(new DefaultProvider());
+// connect the signer to the contract instance
+await instance.connect(your_signer);
+```
+

how-to-call-multiple-contracts.md

@@ -0,0 +1,144 @@
+---
+sidebar_position: 3
+---
+
+# Call Multiple Contracts in a Single Tx
+
+Up to now, we have only shown how to call one smart contract in a transaction. That is, only one input of the tx spends a smart contract UTXO, and the other inputs, if any, spend Pay-to-Public-Key-Hash ([P2PKH](https://learnmeabitcoin.com/guide/p2pkh)) UTXOs, which are generally NOT regarded as smart contracts.
+
+There are cases where it is desirable to spend multiple smart contract UTXOs in different inputs of a tx.
+
+The main differences from [calling a single contract](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call) are:
+
+1. Set `multiContractCall = true` in `MethodCallOptions`
+2. Each call may only return a partial/incomplete transaction, instead of a complete transaction
+3. A partial tx has to be passed as `ContractTransaction` in `MethodCallOptions` in subsequent calls
+4. Finally invoke `SmartContract.multiContractCall(partialContractTx: ContractTransaction, signer: Signer)` to sign and broadcast the complete transaction
+
+
+The following is an [example code](https://github.com/sCrypt-Inc/boilerplate/blob/master/tests/testnet/multi_contracts_call.ts) of calling two contracts at the same time:
+
+
+```ts
+import { Counter } from '../../src/contracts/counter'
+import { getDefaultSigner } from '../utils/helper'
+import { HashPuzzle } from '../../src/contracts/hashPuzzle'
+
+async function main() {
+    await Counter.compile()
+    await HashPuzzle.compile()
+
+    const signer = getDefaultSigner()
+    let counter = new Counter(1n)
+
+    // connect to a signer
+    await counter.connect(signer)
+
+    // contract deployment
+    const deployTx = await counter.deploy(1)
+    console.log('Counter contract deployed: ', deployTx.id)
+
+    counter.bindTxBuilder(
+        'incrementOnChain',
+        (
+            current: Counter,
+            options: MethodCallOptions<Counter>,
+            ...args: any
+        ): Promise<ContractTransaction> => {
+            // create the next instance from the current
+            const nextInstance = current.next()
+            // apply updates on the next instance locally
+            nextInstance.count++
+
+            const tx = new bsv.Transaction()
+            tx.addInput(current.buildContractInput(options.fromUTXO)).addOutput(
+                new bsv.Transaction.Output({
+                    script: nextInstance.lockingScript,
+                    satoshis: current.balance,
+                })
+            )
+
+            return Promise.resolve({
+                tx: tx,
+                atInputIndex: 0,
+                nexts: [
+                    {
+                        instance: nextInstance,
+                        balance: current.balance,
+                        atOutputIndex: 0,
+                    },
+                ],
+            })
+        }
+    )
+
+    const plainText = 'abc'
+    const byteString = toByteString(plainText, true)
+    const sha256Data = sha256(byteString)
+
+    const hashPuzzle = new HashPuzzle(sha256Data)
+
+    // connect to a signer
+    await hashPuzzle.connect(signer)
+
+    const deployTx1 = await hashPuzzle.deploy(1)
+    console.log('HashPuzzle contract deployed: ', deployTx1.id)
+
+    hashPuzzle.bindTxBuilder(
+        'unlock',
+        (
+            current: HashPuzzle,
+            options: MethodCallOptions<HashPuzzle>,
+            ...args: any
+        ): Promise<ContractTransaction> => {
+            if (options.partialContractTx) {
+                const unSignedTx = options.partialContractTx.tx
+                unSignedTx.addInput(
+                    current.buildContractInput(options.fromUTXO)
+                )
+
+                return Promise.resolve({
+                    tx: unSignedTx,
+                    atInputIndex: 1,
+                    nexts: [],
+                })
+            }
+
+            throw new Error('no partialContractTx found')
+        }
+    )
+
+    const partialTx = await counter.methods.incrementOnChain({
+        multiContractCall: true,
+    } as MethodCallOptions<Counter>)
+
+    const finalTx = await hashPuzzle.methods.unlock(
+        byteString,
+        {
+            multiContractCall: true,
+            partialContractTx: partialTx,
+        } as MethodCallOptions<HashPuzzle>
+    )
+
+    const { tx: callTx, nexts } = await SmartContract.multiContractCall(
+        finalTx,
+        signer
+    )
+
+    console.log('Counter, HashPuzzle contract `unlock` called: ', callTx.id)
+
+    // hashPuzzle has terminated, but counter can still be called
+    counter = nexts[0].instance
+}
+
+await main()
+
+```
+
+
+
+:::note
+- You must bind a [transition builder](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#tx-builders) to each contract instance, since [the default](../how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx.md#customize-1) only spends a single contract UTXO.
+- If the called contracts need signatures from different private keys to be called, the signer passed to `multiContractCall` must have all private keys.
+:::
+

how-to-customize-a-contract-tx.md

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# How to Customize a Contract Tx
+
+
+## Deployment Tx
+
+### Default
+For contract deployment, the default tx builder creates a transaction with the following structure:
+
+* Inputs:
+
+  * [0…]: One or more [P2PKH](https://learnmeabitcoin.com/technical/p2pkh) inputs for paying transaction fees.
+
+* Outputs:
+
+  * [0]: The output containing the contract.
+  * [1]: A P2PKH change output if needed.
+
+Numbers in [] represent index, starting from 0.
+
+![](https://lucid.app/publicSegments/view/5242c7cb-d30d-4a92-826c-4d6290e2af04/image.png)
+
+### Customize
+You can customize a contract's deployment tx builder by overriding its [buildDeployTransaction](../how-to-write-a-contract/built-ins#builddeploytransaction) method. An example is shown below.
+
+```ts
+class DemoContract extends SmartContract {
+  // ...
+
+  // customize the deployment tx by overriding `SmartContract.buildDeployTransaction` method
+  override async buildDeployTransaction(utxos: UTXO[], amount: number, 
+    changeAddress?: bsv.Address | string): Promise<bsv.Transaction> {
+    
+    const deployTx = new bsv.Transaction()
+      // add p2pkh inputs for paying tx fees
+      .from(utxos)
+      // add contract output
+      .addOutput(new bsv.Transaction.Output({
+        script: this.lockingScript,
+        satoshis: amount,
+      }))
+      // add OP_RETURN output
+      .addData('Hello World')
+
+    if (changeAddress) {
+      deployTx.change(changeAddress);
+      if (this._provider) {
+        deployTx.feePerKb(await this.provider.getFeePerKb())
+      }
+    }
+
+    return deployTx;
+  }
+}
+```
+
+You may visit the [full code](https://github.com/sCrypt-Inc/boilerplate/blob/f63c37038a03bc51267e816d9441969d3e1d2ece/src/contracts/auction.ts#L100-L127) for more details.
+
+## Call Tx
+
+### Default
+For contract calls, the default tx builder creates a transaction with the following structure:
+
+* Inputs
+
+  * [0]: The input that spends the contract UTXO.
+  * [1…]: Zero or more P2PKH inputs for paying transaction fees.
+
+* Outputs
+
+  * [0…N-1]: One or more outputs, each containing a new contract instance (UTXO) if the contract is [stateful](../how-to-write-a-contract/stateful-contract).
+  * [N]: A P2PKH change output if needed.
+
+![](https://lucid.app/publicSegments/view/9dfde0f0-7275-48da-9411-057e895b5fb3/image.png)
+
+
+### Customize
+
+You can customize a tx builder for a public `@method` of your contract by calling `bindTxBuilder`. The first parameter is the public method name, and the second parameter is the customized tx builder.
+
+```ts
+// bind a customized tx builder for the public method `MyContract.unlock`
+instance.bindTxBuilder("unlock", (current: T, options: MethodCallOptions<T>, ...args: any) => { 
+  // the tx is NOT signed
+  const unsignedTx: bsv.Transaction = new bsv.Transaction()
+    // add contract input
+    .addInput(current.buildContractInput(options.fromUTXO))
+    // add a p2pkh output
+    .addOutput(new bsv.Transaction.Output({
+        script: bsv.Script.fromHex(Utils.buildPublicKeyHashScript(args[0])),
+        satoshis: args[1]
+    }))
+    // add change output
+    .change(options.changeAddress)
+
+  return Promise.resolve({
+    tx: unsignedTx,
+    atInputIndex: 0, // the contract input's index
+    nexts: []
+  })         
+})
+```
+
+Note that the parameters of your customized tx builder consist of the following parts:
+
+- `current` is the actual instance of the smart contract.
+- `options` is of type [`MethodCallOptions`](../how-to-test-a-contract.md#methodcalloptions).
+- `...args: any` is an argument list the same as the bound pubic `@method`.
+
+
+## Notes
+
+Please be aware that each of these tx builders should only create an **unsigned** transaction. If required, the transaction gets signed automatically in a later step prior to broadcasting.
+
+Also, your customized tx must satisfy all of the called `@method`'s assertions.

how-to-debug-a-contract.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 7
+---
+
+# How to Debug a Contract
+
+Debugging an sCrypt contract is as easy as debugging TypeScript, since it is just TypeScript.
+
+
+## Use `console.log()`
+
+You can use `console.log()` to print to the console.
+
+
+```ts
+export class Demo extends SmartContract {
+
+    @prop()
+    readonly x: bigint
+
+    @prop()
+    readonly y: bigint
+
+    constructor(x: bigint, y: bigint) {
+        super(...arguments)
+        this.x = x
+        this.y = y
+    }
+
+    @method()
+    sum(a: bigint, b: bigint): bigint {
+        return a + b
+    }
+
+    @method()
+    public add(z: bigint) {
+        console.log(`z: ${z}`) // print the value of z
+        console.log(`sum: ${this.x + this.y}`) // print the value of this.x + this.y
+        assert(z == this.sum(this.x, this.y), 'incorrect sum')
+    }
+}
+```
+[Try it on Replit](https://replit.com/@msinkec/scryptTS-console-logging)
+
+After running the code, you should see the following output:
+
+```
+z: 3
+sum: 3
+```
+
+
+## Use Visual Studio Code debugger
+
+You can use VS Code to debug sCrypt contracts, the same way as any other TypeScript programs. If you have created a project with [the sCrypt CLI](installation.md), you should have an auto-generated [launch.json](https://github.com/sCrypt-Inc/boilerplate/blob/master/.vscode/launch.json), containing everything needed for the debugger out of the box. To learn more about the VS Code TypeScript debugger, please refer to the [official documentation](https://code.visualstudio.com/docs/TypeScript/TypeScript-debugging).
+
+![](../static/img/debug.jpg)
+You can set some breakpoints and choose `Launch demo` from the `Run and Debug` view (or press **F5**) to start the debugger instantly.
+
+
+![](../static/img/debugging1.gif)
+
+:::note
+You need to change the contract file name in [launch.json](https://github.com/sCrypt-Inc/boilerplate/blob/master/.vscode/launch.json#L13) if needed.
+:::
+
+### Debug a test
+If you want to debug a unit test written with the [Mocha](https://mochajs.org) testing framework, choose `Launch demo test` from the `Run and Debug` view.
+
+
+![](../static/img/debugging2.gif)
+
+:::note
+You need to change the contract test file name in [launch.json](https://github.com/sCrypt-Inc/boilerplate/blob/master/.vscode/launch.json#L25) if needed.
+:::

how-to-debug-scriptcontext.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 4
+---
+
+# How to Debug ScriptContext Failure
+
+
+[ScriptContext](../how-to-write-a-contract/scriptcontext.md) enables the logic of the contract to be executed correctly according to the agreement, and the state of the contract to be propagated correctly.
+
+When it runs incorrectly, you need to master the following methods to locate the error more efficiently.
+
+
+## hashOutputs assertion failed
+
+The `hashOutputs` field of `ScriptContext` is the double SHA256 of the serialization of all output amount (8-byte little endian) with scriptPubKey. Through it, we can agree on how the outputs of the transaction calling the contract should be constructed.
+
+If the output of the transaction is not constructed as required by the contract, then the `hashOutputs` of `ScriptContext` field will not match the the double SHA256 of the `outputs` produced in the code when the contract runs. The following assertion will fail:
+
+```ts
+assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+```
+
+We all know that if the preimage of the hash is inconsistent, the hash value will not match. When an assertion failure occurs, we can only see two mismatched hash values, and cannot visually see the difference between the preimages of the two hash values (that is, the `outputs` in the contract and the outputs of the transaction).
+
+
+A function `diffOutputs` in DebugFunctions Interface is provided to directly compare the difference between the outputs argument and all the outputs of the transaction bound by `this.to`, which are serialized and hashed to produce the `hashOutputs` field of `ScriptContext`.
+
+Just call `this.debug.diffOutputs(outputs)` in the contract:
+
+```ts
+this.debug.diffOutputs(outputs) // diff and print the comparison result
+assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+```
+
+and you will see the comparison result:
+
+![diffoutputs](../../static/img/diffoutputs.png)
+
+Through the printed comparison results, we can intuitively see that the number of satoshis included in the output calculated in the contract is different from the number of satoshis included in the output actually added when constructing the transaction. Now, we have found the source of the error.

how-to-deploy-and-call-a-contract.md

@@ -0,0 +1,365 @@
+---
+sidebar_position: 1
+---
+
+# How to Deploy & Call a Contract
+
+
+## Core Concepts
+After you've finished writing a contract, you can deploy and call it. But first, you should learn how a smart contract interacts with the blockchain. In this section, we will go over some fundamental concepts in detail.
+
+![](../../static/img/call.png)
+[Credit: moonbeam](https://docs.moonbeam.network/tutorials/eth-api/how-to-build-a-dapp)
+
+### Compile the Contract
+
+First, call function `SmartContract.compile()` to compile the contract to Bitcoin script, so it can be included in a transaction's output.
+
+```ts
+await MyContract.compile()
+```
+
+### Contract Instance
+As explained in the [Overview section](../overview.md), an `sCrypt` contract is based on the Bitcoin UTXO model. A **constract instance** is an abstraction that represents a specific contract deployed on-chain, so you can use it to interact with the contract like a normal TypeScript object.
+
+```ts
+// construct a new instance of `MyContract`
+let instance = new MyContract(...initArgs);
+```
+
+### Provider
+
+A `Provider` is an abstraction of a standard Bitcoin node that provides connection to the Bitcoin network, for read and write access to the blockchain.
+
+sCrypt already has a few built-in providers:
+
+* `DummyProvider`: A mockup provider just for local tests. It does not connect to the Bitcoin blockchain and thus cannot send transactions.
+
+* `DefaultProvider`:  The default provider is the safest, easiest way to begin developing on Bitcoin, and it is also robust enough for use in production. It can be used in testnet as well as mainnet.
+
+* See full list of providers [here](../reference/classes/Provider.md#hierarchy).
+
+You can initialize these providers like this:
+
+```ts
+let dummyProvider = new DummyProvider();
+
+// mainnet
+
+let provider = new DefaultProvider();
+
+// testnet
+
+let provider = new DefaultProvider(bsv.Networks.testnet);
+```
+
+### Signer
+
+A `Signer` is an abstraction of private keys, which can be used to sign messages and transactions. A simple signer would be a single private key, while a complex signer is a wallet.
+
+#### TestWallet
+
+For testing purposes only, we have a built-in wallet called `TestWallet`. It can be created like this:
+
+```ts
+const signer = new TestWallet(privateKey, provider);
+```
+
+`privateKey` can be a single private key or an array of private keys that the wallet can use to sign transactions. The ability of the wallet to send transactions is assigned to `provider`. In other words, a `TestWallet` serves as both a signer and a provider.
+
+
+### Tx Builders
+
+To deploy or interact with contracts, we must build transactions and broadcast them to Bitcoin.
+We have some built-in tx builders for the most common way to interact with contracts, so usually you don't have to implement them. If the default tx builder does not meet your specific requirements, such as having extra inputs or outputs in your tx, you can [customize it](./how-to-customize-a-contract-tx.md).
+
+
+#### Contract Deployment Transaction
+
+A Bitcoin transaction is required when deploying a contract to the blockchain. The transaction should have an output, whose script is compiled from the contract. This output is known as a contract UTXO and the contract instance comes `from` this UTXO.
+
+An instance's `from` can be accessed.
+```ts
+// the tx that contains the instance
+instance.from.tx
+// the index of the tx output that contains the instance
+instance.from.outputIndex
+```
+
+#### Contract Call Transaction
+
+When you call a public method of a contract instance in a UTXO, a call transaction is needed. The transaction has an input that references to the UTXO and contains the script consisting of the method's arguments. We regard the contract instance goes `to` this transaction input.
+
+An instance's `to` can be accessed.
+```ts
+// the tx that spends the instance
+instance.to.tx
+// the index of the tx input that spends the UTXO the instance is in
+instance.to.inputIndex
+```
+
+
+This section could be summarized as the diagram below:
+
+![](../../static/img/contract_tx.svg)
+
+
+## Prepare a Signer and Provider
+
+A signer and a provider must be connected to a contract instance before deployment and call. When we are ready to deploy the contract to the testnet/mainnet, we need a real provider like [DefaultProvider](#provider).
+
+```ts
+const network = bsv.Networks.testnet; // or bsv.Networks.mainnet
+const signer = new TestWallet(privateKey, new DefaultProvider(network));
+```
+
+The `privateKey` must have enough coins. Learn how to fund it on a testnet using a [faucet](./faucet).
+
+Then just connect it to your contract instance like this:
+
+```ts
+await instance.connect(signer);
+```
+
+
+## Contract Deployment
+
+To deploy a smart contract, simply call its `deploy` method:
+
+
+```ts
+// construct a new instance of `MyContract`
+let instance = new MyContract(...initArgs);
+
+// connect the signer to the instance
+await instance.connect(signer);
+
+// the contract UTXO’s satoshis
+const initBalance = 1234;
+
+// build and send tx for deployment
+const deployTx = await instance.deploy(initBalance);
+console.log(`Smart contract successfully deployed with txid ${deployTx.id}`);
+```
+
+## Contract Call
+To facilitate calling a contract's public `@method`, we have injected a runtime object named `methods` in your contract class. For each public `@method` of your contract (e.g., `contract.foo`), a function with the same name and signature (including list of parameters and return type, i.e., void) is added into `methods` (e.g., `contract.methods.foo`). In addition, there is an `options` appended as the last paramter.
+
+Assume you have a contract like this:
+
+```ts
+Class MyContract extends SmartContract {
+  ...
+  @method()
+  public foo(arg1, arg2) {...}
+}
+```
+You can check it like this:
+
+```ts
+let instance = new MyContract();
+console.log(typeof instance.methods.foo) // output `function`
+```
+
+This function is designed to invoke the corresponding `@method` of the same name on chain, meaning calling it will spend the previous contract UTXO in a new transaction. You can call it like this:
+
+```ts
+// Note: `instance.methods.foo` should be passed in all arguments and in the same order that `instance.foo` would take.
+
+// Additionally, it can accept an optional "options" argument to control the behavior of the function.
+
+const { tx, atInputIndex } = await instance.methods.foo(arg1, arg2, options);
+```
+
+
+What actually happens during the call is the following.
+
+1. Build an unsigned transaction by calling the tx builder, which can be a default or a customized one introduced in [this section](./how-to-deploy-and-call-a-contract/how-to-customize-a-contract-tx#customizedcalltxbuilder), for a public `@method`.
+
+2. Use the instance's signer to sign the transaction. Note that `instance.foo` could be invoked during this process in order to get a valid unlocking script for the input.
+
+3. User the instance's connected provider to send the transaction.
+
+#### MethodCallOptions
+
+The `options` argument is of type `MethodCallOptions`:
+
+```ts
+/**
+ * A option type to call a contract public `@method` function.
+ * Used to specify the behavior of signers and transaction builders.
+ * For example, specifying a transaction builder to use a specific change address or specifying a signer to use a specific public key to sign.
+ */
+export interface MethodCallOptions<T> {
+  /**
+   * The private key(s) associated with these address(es) or public key(s)
+   * must be used to sign the contract input,
+   * and the callback function will receive the results of the signatures as an argument named `sigResponses`
+   * */
+  readonly pubKeyOrAddrToSign?: PublicKeysOrAddressesOption;
+  /** The subsequent contract instance(s) produced in the outputs of the method calling tx in a stateful contract */
+  readonly next?: StatefulNext<T>[] | StatefulNext<T>,
+  /** The `lockTime` of the method calling tx */
+  readonly lockTime?: number;
+  /** The `sequence` of the input spending previous contract UTXO in the method calling tx */
+  readonly sequence?: number;
+  /** The previous contract UTXO to spend in the method calling tx */
+  readonly fromUTXO?: UTXO;
+  /** The P2PKH change output address */
+  readonly changeAddress?: AddressOption;
+  /** verify the input script before send transaction */
+  readonly verify?: boolean;
+  /** Whether to call multiple contracts at the same time in one transaction */
+  readonly multiContractCall?: true;
+  /** Pass the `ContractTransaction` of the previous call as an argument to the next call, only used if `multiContractCall = true`.  */
+  readonly partialContractTx?: ContractTransaction;
+}
+```
+
+The major differences between here and [local tests](../how-to-test-a-contract.md#test-a-contract-locally) are:
+1. the contract needs to be deployed first;
+2. the contract instance is connected to a real provider, which broadcasts transactions to the blockchain.
+
+### Create a smart contract instance from a transaction
+To interact with a deployed smart contract (i.e., calling its public methods), we need its contract instance corresponding to its latest state on chain, stateful or not. When testing on testnet, we usually put a contract's deployment and its calling (note there could be multiple calls if the contract is stateful) in the same process for convenience, so that we don't need to manage the internal state of the instance manually, because it's always consistent with the transactions on chain.
+
+In reality, a contract's deployment and its call, and its different calls in the case of a stateful contract, may well be in separate processes. For example, the deployment party is different from the calling party, or multiple parties call it. If so, we need to create a contract instance from an on-chain transaction that represents its latest state, before we can call its method.
+
+Typically, we only know the [TXID](https://wiki.bitcoinsv.io/index.php/TXID) of the transaction containing the instance. We can create an instance in two steps:
+1. Using TXID, we retrieve the full transaction by calling [getTransaction](../reference/classes/Provider.md#gettransaction) of the [connected provider](../reference/classes/Signer.md#connectedprovider) of the signer.
+2. We can create an contract instance from a transaction's by calling [fromTx()](../how-to-write-a-contract/built-ins.md#fromtx).
+```ts
+// 1) fetch a transaction from txid
+const tx = await signer.connectedProvider.getTransaction(txId)
+// 2) create instance from transaction
+const instance = Counter.fromTx(tx, atOutputIndex)
+
+// from now on, `instance` is in sync with the on-chain transaction
+// and we can use it to interact with the contract
+```
+
+A complete example can be found [here](./call-deployed).
+
+### Method with Signatures
+
+A contract public `@method` often needs a signature argument for authentication. Take this [Pay To Pubkey Hash (P2PKH)](https://learnmeabitcoin.com/technical/p2pkh) contract for example:
+
+```ts
+export class P2PKH extends SmartContract {
+    @prop()
+    readonly pubKeyHash: PubKeyHash;
+
+    constructor(pubKeyHash: PubKeyHash) {
+        super(..arguments);
+        this.pubKeyHash = pubKeyHash;
+    }
+
+    @method()
+    public unlock(sig: Sig, pubkey: PubKey) {
+        // make sure the `pubkey` is the one locked with its hash value in the constructor
+        assert(hash160(pubkey) == this.pubKeyHash, 'pubKeyHash check failed');
+
+	   // make sure the `sig` is signed by the private key corresponding to the `pubkey`
+        assert(this.checkSig(sig, pubkey), 'signature check failed');
+    }
+}
+```
+
+We can call the `unlock` method like this:
+
+```ts
+// call
+const { tx: callTx } = await p2pkh.methods.unlock(
+    // the first argument `sig` is replaced by a callback function which will return the needed signature
+    (sigResps) => findSig(sigResps, publicKey),
+
+    // the second argument is still the value of `pubkey`
+    PubKey(toHex(publicKey)),
+
+    // method call options
+    {
+        // A request for signer to sign with the private key corresponding to a public key
+        pubKeyOrAddrToSign: publicKey
+    } as MethodCallOptions<P2PKH>
+);
+
+console.log('contract called: ', callTx.id);
+
+```
+
+When `p2phk.method.unlock` is called, the option contains `pubKeyOrAddrToSign`, requesting a signature against `publicKey`.
+
+The first argument is a signature, which can be obtained in a callback function. The function takes a list of signatures requested in `pubKeyOrAddrToSign` and find the one signature to the right public key/address.
+
+In general, if your `@method` needs `Sig`-typed arguments, you could obtain them as follows:
+
+1. Ensure that the `pubKeyOrAddrToSign` contains all public keys/addresses corresponding to these `Sig`s;
+
+2. Replace each `Sig` argument with a callback function that filters to the right `Sig` from the full list of signature in `sigResps`.
+
+
+## Example
+
+Here is the complete sample code for the deployment and call of a P2PKH contract.
+
+```ts
+import { privateKey } from '../../utils/privateKey';
+
+// compile contract
+await P2PKH.compile()
+
+// public key of the `privateKey`
+const publicKey = privateKey.publicKey
+// hash of the `publicKey`
+const pkh = bsv.crypto.Hash.sha256ripemd160(publicKey.toBuffer())
+
+// setup signer
+const signer = new TestWallet(privateKey, new DefaultProvider());
+
+// initialize an instance with `pkh`
+let p2pkh = new P2PKH(PubKeyHash(toHex(pkh)))
+
+// connect the signer
+await p2pkh.connect(signer);
+
+// deploy the contract, with 1 satoshi locked in
+const deployTx = await p2pkh.deploy(1);
+console.log('contract deployed: ', deployTx.id);
+
+// call
+const { tx: callTx } = await p2pkh.methods.unlock(
+    (sigResps) => findSig(sigResps, publicKey),
+    PubKey(toHex(publicKey)),
+    {
+        pubKeyOrAddrToSign: publicKey
+    } as MethodCallOptions<P2PKH>
+);
+
+console.log('contract called: ', callTx.id);
+
+```
+
+More examples can be found [here](https://github.com/sCrypt-Inc/boilerplate/tree/master/tests/testnet).
+
+
+### Running the code
+
+The deployment and call code is wrapped into a simple NPM command:
+
+```sh
+npm run testnet
+```
+
+Make sure you fund your address before running this command.
+After a successful run you should see something like the following:
+
+```
+P2PKH contract deployed:  f3f372aa25f159efa93db8c51a4eabbb15935358417ffbe91bfb78f4f0b1d2a3
+P2PKH contract called:  dc53da3e80aadcdefdedbeb6367bb8552e381e92b226ab1dc3dc9b3325d8a8ee
+```
+
+These are the TXIDs of the transaction which deployed the smart contract and then the one which called its method. You can see the transactions using a [block explorer](https://test.whatsonchain.com/tx/f3f372aa25f159efa93db8c51a4eabbb15935358417ffbe91bfb78f4f0b1d2a3).
+
+
+### Customize Transactions
+Deploying and calling a contract builds transactions with a certain format, which suffices for many cases. In cases where the tx format does not work for you and you need to customize it, please refer to [this section](./how-to-customize-a-contract-tx.md).

how-to-integrate-a-frontend.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 8
+---
+
+# How to Integrate With a Frontend
+
+This section will show how to integrate your smart contract to a frontend, so users can interact with it.
+
+We use [React](https://reactjs.org/) as our frontend framework as an example. We assume that you already have the basic knowledge of frontend development, so we will not spend much time introducing this part of the code, but mostly be focusing on how to interact with the smart contract in the front end project.
+
+:::note
+Currently, the only supported frontend frameworks is React. We anticipate to add supports for other frameworks over time.
+:::
+
+## Setup
+
+### React
+
+Run the following command to create a React project, named `helloworld`.
+
+```bash
+npx create-react-app helloworld --template typescript
+```
+
+![](../../static/img/react-scaffold.png)
+
+We will do most work under the `src` directory.
+
+### `sCrypt`
+
+Run the `init` command of the [CLI](../installation.md#the-scrypt-cli-tool) to turn it into an `sCrypt` project.
+
+```bash
+cd helloworld
+npx scrypt-cli init
+```
+
+This installs all the dependencies and configs the contract development environment.
+After this, we are ready to go!
+
+## Load Contract
+
+Before interacting with a smart contract at the front end, we need to load the contract class in two steps.
+
+
+We'll take a look at how to generate the artifact by ourselves first.
+
+### 1. Compile Contract
+
+Before you start, you need to get the contract source files, as a frontend developer.
+
+Let's use the [Helloworld contract](../tutorials/hello-world.md) as an example. Copy and paste `helloworld.ts` into the `src/contracts` directory.
+
+![](../../static/img/copy-contract-source.png)
+
+Run the following command to compile the contract.
+
+```bash
+npx scrypt-cli compile
+```
+
+![](../../static/img/scrypt-cli-compile.png)
+
+After the compilation, you will get an JSON artifact file at `artifacts/src/contracts/helloworld.json`.
+
+![](../../static/img/contract-artifacts.png)
+
+### 2. Load Artifact
+
+Now with the contract artifact file, you directly load it in the `index.tsx` file.
+
+```ts
+import { Helloworld } from './contracts/helloworld';
+import artifact from '../artifacts/src/contracts/helloworld.json';
+Helloworld.loadArtifact(artifact);
+```
+
+Now you can create an instance from the contract class as before.
+```ts
+const message = toByteString('hello world', true)
+const instance = new Helloworld(sha256(message))
+```
+
+:::info
+You cannot simply call `Helloworld.compile()` at the front end, since it only works in NodeJS, not in browser.
+:::
+
+## Integrate Wallet
+
+You will integrate [Sensilet](https://sensilet.com/), a browser extension wallet similar to [MetaMask](https://metamask.io/), into the project.
+
+:::info
+You can refer to this [guide](../advanced/how-to-add-a-signer.md) to add support for other wallets.
+:::
+
+To request access to the wallet, you can use its `requestAuth` method. 
+
+```ts
+const provider = new DefaultProvider({
+    network: bsv.Networks.testnet
+});
+
+const signer = new SensiletSigner(provider);
+
+// request authentication
+const { isAuthenticated, error } = await signer.requestAuth();
+if (!isAuthenticated) {
+    // something went wrong, throw an Error with `error` message
+    throw new Error(error);
+}
+
+// authenticated
+// you can show user's default address
+const userAddress = await signer.getDefaultAddress();
+// ...
+```
+
+Now you can connect the wallet to the contract instance as before.
+```ts
+await instance.connect(signer);
+```
+
+Afterwards, you can interact with the contract from the front end by [calling its method](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call) as usual.
+
+Go [here](https://academy.scrypt.io) to see a full example on how to build a Tic-Tac-Toe game on chain.

how-to-integrate-dotwallet.md

@@ -0,0 +1,199 @@
+# How to integrate DotWallet
+
+
+[DotWallet](https://www.dotWallet.com/en) is a lightweight wallet designed to help users easily and securely manage their digital assets. We will show how to integrate it with sCrypt-powered apps.
+
+
+## OAuth 2.0
+
+OAuth 2.0 is an industry-standard authorization framework that enables third-party applications to access the resources of a user on a web service —- such as Facebook, Google, and Twitter -- without requiring the user to share their credentials directly with the application. It provides a secure and standardized way for users to grant limited access to their protected resources, such as their profile information or photos, to other applications. 
+It works by introducing an authorization layer between the user, the application, and the web service hosting the user's data. Instead of sharing their username and password with the application, the user is redirected to the web service's authentication server. The user then authenticates themselves on the service, and upon successful authentication, the service issues an access token to the application. This access token represents the user's authorization to access specific resources.
+
+If you are new to OAuth 2.0, check out thse helpful tutorials:
+- [An Illustrated Guide to OAuth and OpenID Connect](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc)
+- [The Simplest Guide To OAuth 2.0](https://darutk.medium.com/the-simplest-guide-to-oauth-2-0-8c71bd9a15bb)
+- [An Introduction to OAuth 2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)
+
+## DotWallet's user authorization
+
+DotWallet uses OAuth 2.0 to allow third-party applications to safely access certain capabilities authorized by DotWallet users. More specifically, it uses Oauth2's authorization code grant type as the diagram shows. See [RFC6749](https://tools.ietf.org/html/rfc6749#section-4.1) for details. 
+
+![](../../static/img/oauth2.png)
+
+[Credit: Vihanga Liyanage](https://medium.com/@vihanga_liyanage/iam-for-dummies-oauth-2-grant-types-397197a26024)
+
+Follow [these steps](https://developers.dotwallet.com/documents/en/#user-authorization) for a user authorization.
+
+1. Construct URI. 
+
+    Example URI: `https://api.ddpurse.com/v1/oauth2/authorize?client_id=YOUR-CLIENT-ID&redirect_uri=http%3A%2F%2FYOUR-REDIRECT-URL&response_type=code&state=YOUR-STATE&scope=user.info`
+
+    URL Parameters:
+
+    | Parameter    | Description |
+    | -------- | ------- |
+    | client_id  | Developer’s dapp client_id    |
+    | redirect_uri  | The redirect URL after authorization. Needs to be url_encoded   |
+    | state    | It is recommended to use a random string of more than 32 bits (such as UUID). The state is used to verify the consistency of the request and callback. This can prevent csrf attacks.  |
+    |response_type | Fill in the fixed value : `code` |
+    |scope | Authorization scope. The list of permissions that the user agrees to authorize. These permissions are required for certain API endpoints. Needs to be url_encoded. Use spaces to separate multiple permissions. For a list of currently supported scope permissions, please check the scope list [here](https://developers.dotwallet.com/documents/en/#user-authorization)|
+
+2. Redirect the user to the URI constructed in step 1
+   
+    After clicking the link, the user will be directed to the DotWallet authorization page. DotWallet will ask the user to log in, and then ask whether they agree to authorize the application for the listed permission scopes.
+
+3. Receive the `code` through the callback uri.
+
+    After the user agrees to authorization in step 2, DotWallet will redirect the client to the `redirect_uri` specified by the application. The authorization code `code` and the provided `state` will be included in the query parameters.
+
+4. Exchange `code` for access_token. The access tokens are credentials used to access protected resources, which are issued by the authorization server.
+   
+:::warning
+To avoid security issues, any request for using or obtaining `access_token` must be made from the backend server. Do not disclose your `access_token` and `client_secret`<sup>1</sup> on the client side.
+:::
+
+
+### DotWallet Developer Platform
+
+1. Before using DotWallet, you need to register and create an app on [DotWallet Developer Platform](https://developers.dotwallet.com/en).
+
+![](../../static/img/dotwallet-create-dapp.png)
+
+2. After creating the app, you will receive an email containing `app_id` and `secret`.
+
+
+![](../../static/img/dotwallet-mail.png)
+
+1. Next, you need to set [redirection URI](https://www.oauth.com/oauth2-servers/redirect-uris). Redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application. For example, in the figure below `http://localhost:3000/callback/` is the redirection.
+
+![](../../static/img/dotwallet-uris.png)
+
+
+:::note
+*Callback domain* in the form is the redirection URIs in OAuth. 
+:::
+
+## Example Implementation
+
+
+Here is an example to integration DotWallet in [Nextjs](https://nextjs.org/), a popular React development framework.
+
+1. Construct URI. 
+
+```ts
+export default async function Home() {
+    const client_id = process.env.CLIENT_ID;
+    const redirect_uri = encodeURIComponent(process.env.REDIRECT_URI || '');
+    const scope = encodeURIComponent("user.info autopay.bsv");
+    const state = crypto.randomUUID();
+    const loginUrl = `https://api.ddpurse.com/authorize?client_id=${client_id}&redirect_uri=${redirect_uri}&response_type=code&scope=${scope}&state=${state}`;
+    
+    return (
+      <main className="flex min-h-screen flex-col items-center justify-between p-24">
+        <div className="m-4 p-4 bg-blue-200 font-bold rounded-lg">
+          <a href={loginUrl}>DotWallet Login</a>
+        </div>
+      </main>
+    );
+}
+```
+
+<center>src/app/page.tsx</center>
+
+
+If the user clicks the **DotWallet Login** link, the page will be redirected to the wallet authorization page.
+
+![](../../static/img/dotwallet-auth.png)
+
+
+2. After the user clicks **Agree to authorize** to log in, the authorization server redirects the user to the redirection URI. The following code receives the `code` through the callback uri,  exchanges the `code` for `access_token` and save it.
+
+Inside the `app` directory, folders are used to [define routes](https://nextjs.org/docs/app/building-your-application/routing/defining-routes#creating-routes) in nextjs. we create `src/app/callback/route.ts` to handle the redirection request.
+
+```ts
+import { redirect, notFound } from 'next/navigation';
+
+import token from "../token"
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const code = searchParams.get('code');
+
+  if (code) {
+    // exchange the code for access_token
+    const res = await fetch(`https://api.ddpurse.com/v1/oauth2/get_access_token`, {
+      body: JSON.stringify({
+        code,
+        redirect_uri: process.env.REDIRECT_URI,
+        grant_type: "authorization_code",
+        client_secret: process.env.CLIENT_SECRET,
+        client_id: process.env.CLIENT_ID,
+      }),
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      method: 'POST'
+    });
+    const { code: apiCode, data, msg } = await res.json();
+
+    if (apiCode === 0) {
+      const { access_token } = data;
+      // save access_token
+      token.access_token = access_token;
+      // redirect to balance page.
+      redirect('/balance');
+    }
+
+  }
+
+  notFound();
+}
+```
+
+<center>src/app/callback/route.ts</center>
+
+
+### `DotWalletSigner`
+
+sCrypt SDK provides `DotWalletSigner` for quick integration with DotWallet.
+
+After redirect to the `/balance` page, we can create a `DotWalletSigner` with the OAuth access token, which is passed as the first argument.
+
+
+```ts
+import { DotwalletSigner, DefaultProvider } from "scrypt-ts";
+import token from "../token";
+
+async function getData() {
+  const provider = new DefaultProvider();
+  const signer = new DotwalletSigner(token.access_token, provider);
+
+  const balance = await signer.getBalance();
+
+  return { balance: balance.confirmed + balance.unconfirmed };
+}
+
+export default async function Balance() {
+  const data = await getData();
+
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-between p-24">
+      <div className="m-4 p-4 bg-blue-200 font-bold rounded-lg">
+        <label>balance</label> {data.balance}
+      </div>
+    </main>
+  );
+}
+
+```
+
+<center>src/app/balance/page.tsx</center>
+
+After creating `DotWalletSigner` with access token, you can call all interfaces of `DotWalletSigner` as in other [signers](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#signer).
+For example, the example uses the signer to check user's balance.
+
+Congrats! You have completed the integration of DotWallet. Full code is [here](https://github.com/zhfnjust/dotwallet-example).
+
+------------------------
+
+[1] `client_secret` is stored in the backend. It's used to exchange authorization code for access token.

how-to-integrate-scrypt-service.md

@@ -0,0 +1,157 @@
+---
+sidebar_position: 5
+---
+
+# How to Integrate sCrypt Service
+
+Before interacting with a `sCrypt` contract, we must create a contract instance representing the latest state of the contract on chain. Such an instance can be created by calling the  [`fromTx`](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#create-a-smart-contract-instance-from-a-transaction) method. However, this means your application needs to track and record all contract-related transactions, especially for a stateful contract.
+
+An easier alternative is to leverage `sCrypt` infrastructure service, which tracks such transactions, so you can focus on your application logic.
+
+## Get Your API Key
+
+### Step 1: Create Your Free Account
+
+Go to the [sCrypt homepage](https://scrypt.io) to create your free account.
+
+![](../../static/img/homepage.png)
+
+### Step 2: Get API Key
+
+Sign in and click on the copy icon to copy your API Key.
+
+![](../../static/img/api-keys.png)
+
+## Integration
+
+Once you have an API key, you can easily integrate sCrypt service into your app by following these simple steps.
+
+### Step 1: Initialize Client
+
+You can pass the API key, along with `network`, to the `Scrypt.init` function to initialize an sCrypt client in your app.
+
+```ts
+import { Scrypt, bsv } from 'scrypt-ts'
+
+Scrypt.init({
+  apiKey: 'YOUR_API_KEY',
+  network: bsv.Networks.testnet,
+})
+```
+
+### Step 2: Connect `ScryptProvider` with your signer
+
+Connect signer to `ScryptProvider`, the required [provider](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#provider) to use sCrypt service.
+
+```ts
+const signer = new TestWallet(myPrivateKey)
+await signer.connect(new ScryptProvider())
+```
+
+### Step 3: Get Contract ID
+
+Each contract is uniquely identified by the transaction that [deploy](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-deployment) it and the output it is in, which we regard as its ID.
+
+```ts
+const counter = new Counter(0n)
+// connect signer
+await counter.connect(signer)
+
+const balance = 1
+const deployTx = await counter.deploy(balance)
+console.log('contract Counter deployed: ', deployTx.id)
+
+const contractId = {
+    /** The deployment transaction id */
+    txId: deployTx.id,
+    /** The output index */
+    outputIndex: 0,
+}
+```
+
+You can usually get the ID of a contract from its creator, who publicizes it so others can interact with it.
+
+### Step 4: Get Contract Instance
+
+Once you have the contract ID, you can easily create a contract instance as follows.
+
+```ts
+const currentInstance = await Scrypt.contractApi.getLatestInstance(
+  Counter,
+  contractId
+)
+
+// connect signer
+await currentInstance.connect(signer)
+```
+For a stateless contract, the instance points to the deployment tx; for a stateful one, it points to the latest tip in a chain of txs, which sCrypt service tracks automatically.
+
+## Interact with the Contract
+Once you have the instance after following the steps above, you can easily read from the contract, write to it, and listen to it.
+
+### Read
+
+You read an instance's properties using the dot operator, like any other object.
+
+```ts
+// read @prop count
+console.log(counter.count)
+```
+
+:::note
+Reading does NOT broadcast a transaction to the blockchain.
+:::
+
+### Write
+
+To update a contract instance, you call its public method as [before](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call), which writes to the blockchain by broadcasting a transaction.
+
+```ts
+// call the method of current instance to apply the updates on chain
+const { tx } = await currentInstance.methods.incrementOnChain()
+
+console.log(`Counter contract called,  tx: ${tx.id}`)
+```
+
+### Listen to Events
+
+Often, your app needs to be notified when a contract gets called and updated. It is essential to be able to listen to such events in real time that can alert your app whenever something relevant occurs on chain. For example, in your front-end, you can refresh the web page to show the user the latest state of a contract, upon event notifications.
+
+With the `sCrypt` service, you can easily subscribe to a contract's events by its contract ID, using the `Scrypt.contractApi.subscribe` method. It takes two parameters:
+
+1. `options: SubscribeOptions<T>`: it includes a contract class, a contract ID, and a optional list of method names monitored.
+
+```ts
+interface SubscribeOptions<T> {
+  clazz: new (...args: any) => T;
+  id: ContractId;
+  methodNames?: Array<string>;
+}
+```
+
+If `methodNames` is set, you will be notified only when public functions in the list are called. Otherwise, you will be notified when ANY public function is called.
+
+2. `callback: (event: ContractCalledEvent<T>) => void`: a callback funciton upon receiving notifications.
+
+`ContractCalledEvent<T>` contains relevant information on how the contract is called:
+
+- `methodName: string`, which public method is called
+
+- `args: SupportedParamType[]`, arguments the public method is called with
+
+- `tx: bsv.Transaction`, transaction where contract is called from
+
+- `nexts: Array[T]`, includes the new contract instances created by this call. If a stateful contract is called, `nexts` contains the contract instances containing the new state generated by this call. You can read the latest state from the new contract instance to, e.g., display the new state to users. If a stateless contract is called, `nexts` is empty.
+
+Below is an example of listening to events when `incrementOnChain` method is called.
+
+```ts
+const subscription = Scrypt.contractApi.subscribe({
+  clazz: Counter, // contract class
+  id: contractId, // contract id
+  methodNames: ['incrementOnChain']
+}, (event: ContractCalledEvent<Counter>) => {
+  // callback when receiving a notification
+  console.log(`${event.methodName} is called with args: ${event.args}`)
+});
+```

how-to-publish-a-contract.md

@@ -0,0 +1,161 @@
+---
+sidebar_position: 9
+---
+
+
+# How to Publish a Contract to NPM
+
+## What is a Smart Contract Library?
+
+A smart contract library can provide methods which can be reused in many contracts. Developers can use existing libraries to reduce the cost of developing their own contracts.
+
+A smart contract library is different from a smart contract in these ways:
+
+* A smart contract library can not have any public/entry `@method`s, which means a library can not be deployed or called directly through a tx. They can only be called within a smart contract or another library.
+
+* A smart contract library can not have any stateful properties, i.e. `@prop(true)` properties. But a property declared as `@prop()` is fine.
+
+## Write a Smart Contract Library
+
+Using `sCrypt` we can create a smart contract library class like this:
+
+```ts
+class MyLib extends SmartContractLib {
+
+  @prop()
+  readonly buf: ByteString;
+
+  constructor(buf: ByteString) {
+    super(...arguments);
+    this.buf = buf;
+  }
+
+  @method()
+  append(content: ByteString) {
+    this.buf += content;
+  }
+
+  @method()
+  static add(x: bigint, y: bigint): bigint {
+    return x + y;
+  }
+
+}
+```
+
+A smart contract library can be declared as a  class that extends `SmartContractLib`. It may also have `@prop`s and `@method`s like smart contracts which have the same rules [introduced before](./how-to-write-a-contract). A smart contract library can be used within `@method`s like this:
+
+```ts
+class MyContract extends SmartContract {
+  @method()
+  public unlock(x: ByteString) {
+    let myLib = new MyLib(hexToByteString('0123'));
+    myLib.append(x);
+    assert(MyLib.add(1n, 2n) === 3n, 'incorrect sum');
+  }
+}
+```
+
+## Test a Smart Contract Library
+
+You can test your smart contract library as a normal class, for example, writing some unit tests:
+
+```ts
+describe('Test SmartContractLib `MyLib`', () => {
+  it('should pass unit test successfully.', () => {
+    expect(MyLib.add(1n, 2n)).to.eq(3n)
+  })
+})
+```
+
+Also you can write a smart contract using the library, then have some tests for the contract, like:
+
+```ts
+class TestLib extends SmartContract {
+  @method
+  public unlock(x: bigint) {
+    assert(MyLib.add(1n, 2n) == x, 'incorrect sum')
+  }
+}
+
+describe('Test SmartContractLib `Lib`', () => {
+  before(async() => {
+    await TestLib.compile()
+  })
+
+  it('should pass integration test successfully.', () => {
+    let testLib = new TestLib()
+    let result = testLib.verify(self => self.unlock(3n))
+    expect(result.success, result.error).to.be.true
+  }
+})
+
+```
+
+## Create and Publish a Library Project Using sCrypt CLI
+
+The following command will create a demo scryptTS library along with tests and  scaffolding:
+
+```sh
+scrypt project --lib <your-lib-name>
+```
+
+Note the `lib` option is turned on.
+
+You can publish the library on [NPM](https://www.npmjs.com/) by running the following command in the project's root directory:
+
+```sh
+npm publish
+```
+
+This will build the project and publish it on NPM. After the library is published, users can simply import it in any other project just like regular NPM packages.
+
+:::note
+Named imports are not supported yet. You should only import like the following.
+:::
+
+```ts
+import { MyLib } from “my_package”
+```
+
+### Advanced
+
+For the import system working properly, you should always publish the auto-generated sCrypt contracts (including `scrypt.index.json` file) along with the javascript outputs. The structure of the package could be like this:
+
+```
+node_modules
+|__ my_package
+    |__ dist
+        |__ myLib.js
+        |__ myLib.d.ts
+    |__ artifacts
+        |__ myLib.scrypt
+    |__ scrypt.index.json
+    …
+```
+
+The `scrypt.index.json` file will be generated at TypeScript compile time in the same directory of your `tsconfig.json` which should be placed in the root folder. It shall not be moved or modified manually. The folder for auto-generated `.scrypt` files (`artifacts` in the upper file tree) can be changed by configuring the `outDir` option in `tsconfig.json`, like:
+
+```json
+"compilerOptions": {
+  "plugins": [
+    {
+      "transform": "scrypt-ts/dist/transformation/transformer",
+      "transformProgram": "true",
+      "outDir": "my_scrypts_dir"
+    }
+  ]
+}
+```
+
+You should always publish the auto-generated sCrypt files along with the package. If you are familiar with sCrypt development and want to apply some improvements to the auto-generated files, for example using an inline asm function to replace an ordinary function to reduce the final script size, you could just modify the auto-generated file as you wish before publishing it. Take a look at how [scrytp-ts-lib](https://github.com/sCrypt-Inc/scrypt-ts-lib/tree/master/optimizations) does it.
+
+:::note
+You should modify the auto-generated files with caution and make sure that the modification passes the tests.
+:::
+
+## Related Tools
+
+### `scrypt-ts-lib`
+
+It’s a collection of smart contract libraries provided by us. You can find some useful tools [here](https://github.com/sCrypt-Inc/scrypt-ts-lib). Also you are welcome to contribute.

how-to-test-a-contract.md

@@ -0,0 +1,270 @@
+---
+sidebar_position: 5
+---
+
+# How to Test a Contract
+
+Before using a smart contract in production, one should always test it carefully, especially because any bug in it may cause **real economic losses**.
+
+There are two different kinds of tests recommended for every project using `sCrypt`:
+
+* **Local Unit Testing**
+* **Testnet Integration Testing**
+
+Now we will take a look at the file `tests/local/demo.ts`. This file contains code for deployment of our `Demo` contract on the Bitcoin testnet and a subsequent public method call on the contract.
+
+But before going into details, you should learn some basic models of sCrypt for signing and sending transactions.
+
+## Compile the Contract
+
+First, call function `SmartContract.compile()` to compile the contract before doing any testing.
+
+```ts
+await Demo.compile()
+```
+
+## Provider
+
+A `Provider` is an abstraction of a standard Bitcoin node that provides connection to the Bitcoin network, for read and write access to the blockchain.
+
+sCrypt already has a few built-in providers:
+
+* `DummyProvider`: A mockup provider just for local tests. It does not connect to the Bitcoin blockchain and thus cannot send transactions.
+
+* `DefaultProvider`:  The default provider is the safest, easiest way to begin developing on Bitcoin, and it is also robust enough for use in production. It can be used in testnet as well as mainnet.
+
+* See full list of providers [here](./reference/classes/Provider.md#hierarchy).
+
+You can initialize these providers like this:
+
+```ts
+let dummyProvider = new DummyProvider();
+
+// Mainnet
+let provider = new DefaultProvider();
+// Or explicitly: let provider = new DefaultProvider(bsv.Networks.mainnet);
+
+// Testnet
+let provider = new DefaultProvider(bsv.Networks.testnet);
+```
+
+## Signer
+
+A `Signer` is an abstraction of private keys, which can be used to sign messages and transactions. A simple signer would be a single private key, while a complex signer is a wallet.
+
+### TestWallet
+
+For testing purposes only, we have a built-in wallet called `TestWallet`. It can be created like this:
+
+```ts
+const signer = new TestWallet(privateKey, provider);
+```
+
+`privateKey` can be a single private key or an array of private keys that the wallet can use to sign transactions. The ability of the wallet to send transactions is assigned to `provider`. In other words, a `TestWallet` serves as both a signer and a provider.
+
+## Test a Contract Locally
+
+Compared to other blockchains, smart contracts on Bitcoin are **pure**.
+
+* Given the same input, its public method always returns the same boolean output: success or failure. It has no internal state.
+* A public method call causes no side effects.
+
+Smart contracts are similar to mathematical functions. Thus, we can test a contract locally without touching the Bitcoin blockchain. If it passes tests off chain, we are confident it will behave the same on chain.
+
+### Prepare a Signer and Provider
+
+For local testing, we can use the `TestWallet`, with a mock provider. The `TestWallet` and `DummyProvider` combination would be ideal for local tests because it can sign the contract call transactions without actually sending them.
+
+Such a signer may be declared as below:
+
+```ts
+let signer = new TestWallet(privateKey, new DummyProvider());
+```
+
+Don't forget to connect the signer to the contract instance as well:
+
+```ts
+await instance.connect(signer);
+```
+
+### Call a Public Method
+
+Similar to what we described in [this section](../how-to-test-a-contract#call-a-public-method), you can call a contract's public `@method` on the blockchain as follows:
+
+```ts
+// build and send tx for calling `foo`
+const { tx, atInputIndex } = await instance.methods.foo(arg1, arg2, options);
+console.log(`Smart contract method successfully called with txid ${tx.id}`);
+```
+
+Remember that the tx is not actually sent anywhere in a local test because we connect to a mock provider.
+
+### Verify the Tx input for the method call
+
+In the previous step, the signed `tx` for the contract call and its input index are returned. You can call `verifyScript` on the returned `tx` to verify that the contract method call at the given tx input index is successful.
+
+```ts
+let result = tx.verifyScript(atInputIndex)
+console.log(result.success) // Output: true or false
+```
+
+### Integrate with a testing framework
+
+You can use whatever testing framework you like to write unit tests for your contract. For example, a local test using [Mocha](https://mochajs.org/) is shown below:
+
+```js
+describe('Test SmartContract `Demo`', () => {
+  let signer;
+  let demo;
+
+  before(async () => {
+    // compile contract
+    await Demo.compile()
+
+    // create a test wallet as signer, connected to a dummy provider
+    signer = new TestWallet(privateKey, new DummyProvider())
+
+    // initialize a contract instance
+    demo = new Demo(1n, 2n)
+
+    // connect the instance to signer
+    await demo.connect(signer)
+  })
+
+  it('should pass the public method unit test successfully.', async () => {
+    // call `demo.methods.add` to get a signed tx
+    const { tx: callTx, atInputIndex } = await demo.methods.add(
+      // pass in the right argument
+      3n,
+      // set method call options
+      {
+        // Since `demo.deploy` hasn't been called before, a fake UTXO of the contract should be passed in.
+        fromUTXO: dummyUTXO
+      } as MethodCallOptions<Demo>
+    )
+
+    let result = callTx.verifyScript(atInputIndex)
+    expect(result.success, result.error).to.eq(true)
+  })
+
+  it('should pass the non-public method unit test', () => {
+    expect(demo.sum(3n, 4n)).to.be.eq(7n)
+  })
+
+  it('should throw error', () => {
+    return expect(
+	  // Using the wrong argument when calling this function just results in an error.
+      demo.methods.add(4n, { fromUTXO: dummyUTXO })
+    ).to.be.rejectedWith(/add check failed/)
+  })
+})
+```
+
+ ## Test a Stateful Contract
+
+Stateful contact testing is very similar to what we have described above. The only different is that you have to be aware of smart contract instance changes after method calls.
+
+As described in the [Overview](./how-to-write-a-contract/stateful-contract.md#overview), for each method call, a tx contains new contract UTXO(s) with the latest updated state, i.e., the next instance. From the perspective of the current spending tx, the public `@method` of a contract instance is called in one of its inputs, and the next contract instance is stored in one (or more) of its outputs.
+
+Now, let's look at how to test the `incrementOnChain` method call:
+
+```ts
+// initialize the first instance, i.e., deployment
+let counter = new Counter(0n);
+// connect it to a signer
+counter.connect(dummySigner());
+
+// set the current instance to be the first instance
+let current = counter;
+
+// create the next instance from the current
+let nextInstance = current.next();
+
+// apply the same updates on the next instance locally
+nextInstance.increment();
+
+// call the method of current instance to apply the updates on chain
+const { tx: tx_i, atInputIndex } = await current.methods.incrementOnChain(
+  {
+    // Since `counter.deploy` hasn't been called before, a fake UTXO of the contract should be passed in.
+    fromUTXO: getDummyUTXO(balance),
+
+    // the `next` instance and its balance should be provided here
+    next: {
+      instance: nextInstance,
+      balance
+    }
+  } as MethodCallOptions<Counter>
+);
+
+// check the validity of the input script generated for the method call.
+let result = tx_i.verifyScript(atInputIndex);
+expect(result.success, result.error).to.eq(true);
+
+```
+
+In general, we call the method of a stateful contract in 3 steps:
+
+### 1. Build the `current` instance
+
+The `current` instance refers to the contract instance containing the latest state on the blockchain. The first instance is in the deployment transaction. In the above example, we initialize the `current` instance to be the first instance like this:
+
+```ts
+let current = counter;
+```
+
+### 2. Create a `next` instance and apply updates to it off chain
+
+The `next` instance is the new instance in the UTXO of the method calling tx.
+
+To create the `next` of a specific contract instance, you can simply call `next()` on it:
+
+```ts
+let nextInstance = instance.next();
+```
+
+It will make a deep copy of all properties and methods of `instance` to create a new one.
+
+Then, you should apply all the state updates to the `next` instance. Please note that these are just local/off-chain updates and are yet to be applied to the blockchain.
+
+```ts
+nextInstance.increment();
+```
+This is the **SAME** method we call on chain in `incrementOnChain`, thanks to the fact that both the on-chain smart contract and off-chain code are written in TypeScript.
+
+### 3. Call the method on the `current` instance to apply updates on chain
+
+As described in [this section](#call-a-public-method), we can build a call transaction. The only difference here is that we pass in the `next` instance and its balance as a method call option in a stateful contract. So the method (i.e., `incrementOnChain`) have all the information to verify that all updates made to the `next` instance follow the state transition rules in it.
+
+```ts
+const { tx: tx_i, atInputIndex } = await current.methods.incrementOnChain(
+  {
+    // Since `counter.deploy` hasn't been called before, a fake UTXO of the contract should be passed in.
+    fromUTXO: getDummyUTXO(balance),
+
+    // the `next` instance and its balance should be provided here
+    next: {
+      instance: nextInstance,
+      balance
+    }
+  } as MethodCallOptions<Counter>
+);
+```
+
+Finally, we can check the validity of the method call as before.
+
+```ts
+let result = tx_i.verifyScript(atInputIndex);
+expect(result.success, result.error).to.eq(true);
+```
+
+### Running the tests
+
+As before, we can just use the following command:
+
+```sh
+npm run test
+```
+Full code is [here](https://github.com/sCrypt-Inc/boilerplate/blob/master/tests/local/counter.test.ts).
+
+You may visit [here](./how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md) to see more details on contract deployment and call.

how-to-verify-a-contract.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 11
+---
+
+# How to Verify a Contract
+
+You will learn how to verify smart contracts on [WhatsOnChain](https://whatsonchain.com/) (WoC), a blockchain explorer.
+By verifying your smart contract on WoC, anyone can view its source code and interact with it confidently. Let's get started!
+
+
+To start with the verification process, we need to first deploy a smart contract. Let us use the ["Hello World" tutorial](./tutorials/hello-world.md) as an example. After you complete the tutorial, you should get the ID of the deployment transaction such as [`a34d4e45a9108b5b9da4faf4f086e9ef36b79466383bd7a22ff2c7f6a562546c`](https://test.whatsonchain.com/tx/a34d4e45a9108b5b9da4faf4f086e9ef36b79466383bd7a22ff2c7f6a562546c).
+
+
+If you take a look at the transaction on WoC, you'll see that the first output contains a script identified by the hash `eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def`, which contains your contract in script format.
+
+![](../static/img/verify-tx-out.png)
+
+This hash is referred to as the `scriptHash`. It's essentially just a `sha256` hash value of the deployed contracts locking script, encoded in a little-endian hex format. It is commonly used as an index by block explorers. You can also get this value locally, via the contract instance's `scriptHash` property:
+
+```ts
+console.log(instance.scriptHash)
+// eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def
+```
+
+:::note
+The scriptHash value can vary due to factors like the current property values and the number of times the contract has been updated, leading to inconsistencies in its value. 
+:::
+
+You can submit and verify sCrypt source code that belongs to a specific script hash.
+
+![](../static/img/verify-diagram.webp)
+
+There are two ways to verify it.
+
+## 1. Using WOC sCrypt Plugin
+
+At the deployed transaction on WOC, click on the `ScriptHash` of the first output. It will open a page like this:
+
+![](../static/img/verify-scripthash.png)
+
+You shall see an `sCrypt` tab. Click on it. You'll see a very simple form:
+
+
+![](../static/img/verify-submit.png)
+
+In the form you are able to select the version of sCrypt you've used to compile and deploy the contract, along with a text-box in which you need to paste the source code.
+
+
+![](../static/img/verify-submit-filled.png)
+
+
+Now click `Submit`. If the code is correct, you should see something like the following in a few seconds:
+
+
+![](../static/img/verify-verified-code.png)
+
+Congrats, you have verified your first smart contract!
+
+Now, every time someone opens the `sCrypt` tab on [the script hash page](https://test.whatsonchain.com/script/eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def), they will see the verified smart contract source code, as well as its constructor parameters when deployed.
+
+## 2. Using CLI
+
+The same process can be done using the [sCrypt CLI](https://www.npmjs.com/package/scrypt-cli). 
+You can verify the deployed smart contracts script using the `verify` command:
+
+```sh
+scrypt verify <scriptHash> <contractPath>
+```
+
+The first positional argument is the script hash of the deployed contract and the second one is the path to the file which contains the sCrypt smart contract. Note, that the file must also include all the code it depends on, i.e. third party libraries.
+
+Using the `network` option, you can specify on which network the contract is deployed. This defaults to `test`, indicating the Bitcoin testnet:
+
+```sh
+scrypt verify --network main <scriptHash> <contractPath>
+```
+
+You can also specify the version of sCrypt used during verification. By default, the command will use the version specified in `package.json`:
+
+```sh
+scrypt verify -V 0.2.0-beta.9 <scriptHash> <contractPath>
+```
+
+For example, if we would like to verify the same deployed contract as above, we would simply run the following:
+
+```sh
+scrypt verify eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def src/contracts/demoproject.ts
+```
+
+Upon execution, the designated contract code undergoes verification on sCrypt's servers. If successful, the outcome will be [displayed on WoC](https://test.whatsonchain.com/script/eb2f10b8f1bd12527f07a5d05b40f06137cbebe4e9ecfb6a4e0fd8a3437e1def), under the "sCrypt" tab, just like above.
+

how-to-write-a-contract.md

@@ -0,0 +1,658 @@
+---
+sidebar_position: 1
+---
+
+# How to Write a Contract
+
+A smart contract is a class that extends the `SmartContract` base class. A simple example is shown below.
+
+```ts
+import { SmartContract, method, prop, assert } from "scrypt-ts"
+
+class Demo extends SmartContract {
+  @prop()
+  readonly x: bigint
+
+  constructor(x: bigint) {
+    super(...arguments)
+    this.x = x
+  }
+
+  @method()
+  public unlock(x: bigint) {
+    assert(this.add(this.x, 1n) == x, 'incorrect sum')
+  }
+
+  @method()
+  add(x0: bigint, x1:bigint) : bigint {
+    return x0 + x1
+  }
+}
+```
+
+Class members decorated with `@prop` and `@method` will end up on the blockchain and thus must be a strict subset of TypeScript. Everywhere decorated with them can be regarded in the on-chain context. Members decorated with neither are regular TypeScript and are kept off chain. The significant benefit of `sCrypt` is that both on-chain and off-chain code are written in the same language: TypeScript.
+
+:::note
+You can use [the sCrypt template Repl](https://replit.com/@msinkec/sCrypt) and play with the code in your browser!
+:::
+
+## Properties
+
+A smart contract can have two kinds of properties:
+
+1. With `@prop` decorator: these properties are **only allowed to have [types](#data-types) specified below** and they shall only be initialized in the constructor.
+
+2. Without `@prop` decorator: these properties are regular TypeScript properties without any special requirement, meaning they can use any types. Accessing these properties is prohibited in methods decorated with the `@method` decorator.
+
+
+### `@prop` decorator
+
+Use this decorator to mark any property that intends to be stored on chain.
+
+This decorator takes a `boolean` parameter. By default, it is set to `false`, meaning the property cannot be changed after the contract is deployed. If the value is `true`, the property is a so-called [stateful](./stateful-contract) property and its value can be updated in subsequent contract calls.
+
+```ts
+// good, `a` is stored on chain, and it's readonly after the contract is deployed
+@prop()
+readonly a: bigint
+
+// valid, but not good enough, `a` cannot be changed after the contract is deployed
+@prop()
+a: bigint
+
+// good, `b` is stored on chain, and its value can be updated in subsequent contract calls
+@prop(true)
+b: bigint
+
+// invalid, `b` is a stateful property that cannot be readonly
+@prop(true)
+readonly b: bigint
+
+// good
+@prop()
+static c: bigint = 1n
+
+// invalid, static property must be initialized when declared
+@prop()
+static c: bigint
+
+// invalid, stateful property cannot be static
+@prop(true)
+static c: bigint = 1n
+
+// good, `UINT_MAX` is a compile-time constant, and no need to typed explicitly
+static readonly UINT_MAX = 0xffffffffn
+
+// valid, but not good enough, `@prop()` is not necessary for the CTC
+@prop()
+static readonly UINT_MAX = 0xffffffffn
+
+// invalid
+@prop(true)
+static readonly UINT_MAX = 0xffffffffn
+```
+
+## Constructor
+
+A smart contract must have an explicit constructor if it has at least one `@prop` that is not `static`.
+
+The `super` method **must** be called in the constructor and all the arguments of the constructor should be passed to `super`
+in the same order as they are passed into the constructor. For example,
+
+```ts
+class A extends SmartContract {
+  readonly p0: bigint
+
+  @prop()
+  readonly p1: bigint
+
+  @prop()
+  readonly p2: boolean
+
+  constructor(p0: bigint, p1: bigint, p2: boolean) {
+    super(...arguments)  // same as super(p0, p1, p2)
+    this.p0 = p0
+    this.p1 = p1
+    this.p2 = p2
+  }
+}
+```
+[`arguments`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments) is an array containing the values of the arguments passed to that function. `...` is the [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax).
+
+
+## Methods
+
+Like properties, a smart contract can also have two kinds of methods:
+
+1. With `@method` decorator: these methods can only call **methods also decorated by `@method` or [functions](#functions) specified below**. Also, **only the properties decorated by `@prop` can be accessed**.
+
+2. Without `@method` decorator: these methods are just  regular TypeScript class methods.
+
+
+### `@method` decorator
+
+1. Use this decorator to mark any method that intends to run on chain.
+2. It takes a [sighash flag](./scriptcontext.md#sighash-type) as a parameter.
+
+
+### Public `@method`s
+
+Each contract **must** have at least one public `@method`. It is denoted with the `public` modifier and does not return any value. It is visible outside the contract and acts as the main method into the contract (like `main` in C and Java).
+
+A public `@method` can be called from an external transaction. The call succeeds if it runs to completion without violating any conditions in [assert()](./built-ins.md#assert). An example is shown below.
+
+```ts
+@method()
+public unlock(x: bigint) {
+  // only succeeds if x is 1
+  assert(this.add(this.x, 1n) == x, "unequal")
+}
+```
+
+:::note
+The last function call of a public `@method` method **must** be an `assert()` function call, unless it is a `console.log()` call.
+:::
+
+```ts
+class PublicMethodDemo extends SmartContract {
+  @method()
+  public foo() {
+    // invalid, the last statement of public method should be an `assert` function call
+  }
+
+  @method()
+  public bar() {
+    assert(true);
+    return 1n;  // invalid, because a public method cannot return any value
+  }
+
+  @method()
+  public foobar() {
+      console.log();
+      // valid, `console.log` calling will be ignored when verifying the last `assert` statement
+      assert(true);
+      console.log();
+      console.log();
+  }
+}
+```
+
+### Non-public `@method`s
+
+Without a `public` modifier, a `@method` is internal and cannot be directly called from an external transaction.
+
+```ts
+@method()
+add(x0: bigint, x1:bigint) : bigint {
+  return x0 + x1
+}
+```
+
+:::note
+**Recursion is disallowed**. A `@method`, public and not, cannot call itself, either directly in its own body or indirectly calls another method that transitively calls itself.
+:::
+
+```ts
+class MethodsDemo extends SmartContract {
+  @prop()
+  readonly x: bigint;
+  @prop()
+  readonly y: bigint;
+
+  constructor(x: bigint, y: bigint) {
+    super(...arguments);
+    this.x = x;
+    this.y = y;
+  }
+
+  // good, non-public static method without access `@prop` properties
+  @method()
+  static sum(a: bigint, b: bigint): bigint {
+    return a + b;
+  }
+
+  // good, non-public method
+  @method()
+  xyDiff(): bigint {
+    return this.x - this.y
+  }
+
+  // good, public method
+  @method()
+  public add(z: bigint) {
+    // good, call `sum` with the class name
+    assert(z == MethodsDemo.sum(this.x, this.y), 'add check failed');
+  }
+
+  // good, another public method
+  @method()
+  public sub(z: bigint) {
+    // good, call `xyDiff` with the class instance
+    assert(z == this.xyDiff(), 'sub check failed');
+  }
+
+  // valid but bad, public static method
+  @method()
+  public static alwaysPass() {
+    assert(true)
+  }
+}
+```
+
+## Data Types
+
+Types used in `@prop` and `@method` are restricted to these kinds:
+
+### Basic Types
+
+#### boolean
+
+A simple value `true` or `false`.
+```ts
+let isDone: boolean = false
+```
+
+#### `bigint`
+
+`bigint` can represent arbitrarily large integers. A  [bigint literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) is a number with suffix `n`:
+
+```ts
+11n
+0x33FEn
+const previouslyMaxSafeInteger = 9007199254740991n
+const alsoHuge = BigInt(9007199254740991)
+// 9007199254740991n
+const hugeHex: bigint = BigInt("0x1fffffffffffff")
+// 9007199254740991n
+```
+
+#### `ByteString`
+
+In a smart contract context (i.e., in `@method`s or `@prop`s), a `ByteString` represents a byte array.
+
+A literal `string` can be converted in to a `ByteString` using function `toByteString(literal: string, isUtf8: boolean = false): ByteString`:
+
+* If not passing `isUtf8` or `isUtf8` is `false`, then `literal` should be in the format of hex literal, which can be represented by the regular expression: `/^([0-9a-fA-F]{2})*$/`
+* Otherwise, `literal` should be in the format of utf8 literal, e.g., `hello world`.
+
+:::note
+`toByteString` **ONLY** accepts string literals for its first argument, and boolean literals for the second.
+:::
+
+```ts
+let a = toByteString('0011') // valid, `0011` is a valid hex literal
+// 0011
+let b = toByteString('hello world', true) // valid
+// 68656c6c6f20776f726c64
+
+toByteString('0011', false) // valid
+// 30303131
+
+toByteString(b, true) // invalid, not passing string literal to the 1st parameter
+
+toByteString('001') // invalid, `001` is not a valid hex literal
+toByteString('hello', false) // invalid, `hello` is not a valid hex literal
+
+toByteString('hello', 1 === 1) // invalid, not passing boolean literal to the 2nd parameter
+
+let c = true
+toByteString('world', c) // invalid, not passing boolean literal to the 2nd parameter
+```
+
+`ByteString` has the following operators and methods:
+
+* `==` / `===`: compare
+
+* `+`: concatenate
+
+```ts
+const str0 = toByteString('01ab23ef68')
+const str1 = toByteString('656c6c6f20776f726c64')
+
+// comparison
+str0 == str1
+str0 === str1
+// false
+
+// concatenation
+str0 + str1
+// '01ab23ef68656c6c6f20776f726c64'
+```
+
+#### `number`
+
+Type `number` is not allowed in `@prop`s and `@method`s, except in the following cases. We can use `Number()` function to convert `bigint` to `number`.
+
+* Array index
+
+```ts
+let arr: FixedArray<bigint, 3> = [1n, 3n, 3n]
+let idx: bigint = 2n
+let item = arr[Number(idx)]
+```
+
+* Loop variable
+
+``` ts
+for (let i: number = 0 i < 10 i++) {
+  let j: bigint = BigInt(i) // convert number to bigint
+}
+```
+
+It can also be used in defining [compile-time constants](#compile-time-constant).
+
+
+### Fixed Size Array
+
+All arrays **must** be of fixed size and be declared as type of `FixedArray<T, SIZE>`, whose `SIZE` must be a [CTC](#compile-time-constant) described later.
+The common TypeScript arrays declared as `T[]` or `Array<T>` are not allowed in `@prop`s and `@method`s, as they are of dynamic size.
+
+```ts
+let aaa: FixedArray<bigint, 3> = [1n, 3n, 3n]
+
+// set to all 0s
+const N = 20
+let aab: FixedArray<bigint, N> = fill(0n, N)
+
+// 2-dimensional array
+let abb: FixedArray<FixedArray<bigint, 2>, 3> = [[1n, 3n], [1n, 3n], [1n, 3n]]
+```
+
+:::caution
+A `FixedArray` behaves differently in an on-chain and off-chain context, when passed as a function argument. It is *passed by reference* off chain, as a regular TypeScript/JavaScript array, while *passed by value* on chain. It is thus strongly recommended to NEVER mutate a `FixedArray` parameter's element inside a function.
+
+```ts
+class DemoContract extends SmartContract {
+
+    @prop(true)
+    readonly a: FixedArray<bigint, 3>
+
+    constructor(a: FixedArray<bigint, 3>) {
+        super(...arguments)
+        this.a = a
+    }
+
+    @method()
+    onchainChange(a: FixedArray<bigint, 3>) {
+        a[0] = 0
+    }
+
+    offchainChange(a: FixedArray<bigint, 3>) {
+        a[0] = 0
+    }
+
+    @method()
+    public main(a: FixedArray<bigint, 3>) {
+      this.onchainChange(this.a)
+      // note: a[0] is not changed on chain
+      assert(this.a[0] == 1n)
+    }
+}
+
+const arrayA: FixedArray<bigint, 3> = [1n, 2n, 3n]
+const instance = new DemoContract(arrayA);
+
+instance.offchainChange(arrayA)
+// note: arrayA[0] is changed off chain
+assert(arrayA[0] = 0n)
+```
+:::
+
+### User-defined Types
+
+Users can be define customized types using `type` or `interface`, made of basic types.[^1]
+
+```ts
+type ST = {
+  a: bigint
+  b: boolean
+}
+
+interface ST1 {
+  x: ST
+  y: ByteString
+}
+
+type Point = {
+  x: number
+  y: number
+}
+
+function printCoord(pt: Point) {
+  console.log("The coordinate's x value is " + pt.x)
+  console.log("The coordinate's y value is " + pt.y)
+}
+
+interface Point2 {
+  x: number
+  y: number
+}
+
+// Exactly the same as the earlier example
+function printCoord(pt: Point2) {
+  console.log("The coordinate's x value is " + pt.x)
+  console.log("The coordinate's y value is " + pt.y)
+}
+
+```
+
+[^1]: A user-defined type is also passed by value on chain, and by reference off chain, same as a `FixedArray`. It is thus strongly recommended to NEVER mutate the field of a parameter, which is of a user-defined type, inside a function.
+
+### Domain Types
+
+There are several domain types, specific to the Bitcoin context, used to further improve type safety. They are all subtypes of `ByteString`. That is, they can be used where a `ByteString` is expected, but not vice versa.
+
+
+* `PubKey` - a public key
+
+* `Sig` - a signature type in [DER format](https://academy.bit2me.com/en/que-son-firmas-estrictas-der), including sighash flags at the end
+
+* `Ripemd160` - a RIPEMD-160 hash
+
+* `PubKeyHash` - an alias for `Ripemd160`, usually representing a bitcoin address.
+
+* `Sha1` - a SHA-1 hash
+
+* `Sha256` - a SHA-256 hash
+
+* `SigHashType` - a sighash
+
+* `SigHashPreimage` - a sighash preimage
+
+* `OpCodeType` - a Script [opcode](https://wiki.bitcoinsv.io/index.php/Opcodes_used_in_Bitcoin_Script)
+
+```ts
+@method()
+public unlock(sig: Sig, pubkey: PubKey) {
+    // hash160() takes a ByteString as input, but can accept pubkey here, which if of type PubKey
+    assert(hash160(pubkey) == this.pubKeyHash)
+    assert(this.checkSig(sig, pubkey), 'signature check failed')
+}
+```
+
+## Statements
+
+There are some constraints on these following statements within `@method`s, except [variable declarations](#Variable-declarations).
+
+### Variable declarations
+
+Variables can be declared in `@method`s by keywords `const` / `var` / `let`, like in normal TypeScript.
+
+```ts
+let a : bigint = 1n
+var b: boolean = false
+const byte: ByteString = toByteString("ff")
+```
+
+### `for`
+
+Bitcoin does not allow unbounded loops for security reasons, to prevent DoS attacks. All loops must be bounded at compile time. So if you want to loop inside `@method`, you must strictly use the following format:
+
+```ts
+for (let $i = 0; $i < $maxLoopCount; $i++) {
+  ...
+}
+```
+
+:::note
+* the initial value must be `0` or `0n`, the operator `<` (no `<=`), and increment `$i++` (no pre-increment `++$i`).
+* `$maxLoopCount` must be a [CTC](#compile-time-constant).
+* `$i` can be arbitrary name, e.g., `i`, `j`, or `k`. It can be both a `number` or a `bigint` type.
+* `break` and `continue` are currently not allowed, but can be emulated like
+:::
+
+```ts
+// emulate break
+let x = 3n
+let done = false
+for (let i = 0; i < 3; i++) {
+    if (!done) {
+        x = x * 2n
+        if (x >= 8n) {
+            done = true
+        }
+    }
+}
+```
+
+### `return`
+
+Due to the lack of native return semantics support in Bitcoin Script, a function currently must end with a `return` statement and it is the only valid place for a `return` statement. This requirement may be relaxed in the future.
+
+```ts
+@method() m(x: bigint): bigint {
+   if (x > 2n) return x  // invalid
+   return x + 1n         // valid
+}
+```
+
+This is usually not a problem since it can be circumvented as follows:
+```ts
+@method()
+abs(a: bigint): bigint {
+    if (a > 0) {
+        return a
+    } else {
+        return -a
+    }
+}
+```
+can be rewritten as
+```ts
+@method()
+abs(a: bigint): bigint {
+    let ret : bigint = 0
+
+    if (a > 0) {
+        ret = a
+    } else {
+        ret = -a
+    }
+    return ret
+}
+```
+
+## Compile-time Constant
+
+A compile-time constant, CTC for short, is a special variable whose value can be determined at compile time. A CTC must be defined in one of the following ways.
+
+
+* A number literal like:
+
+```ts
+3
+```
+
+* A `const` variable, whose value must be a numeric literal. Expressions cannot be used for now.
+
+```ts
+const N1 = 3 // valid
+const N2: number = 3 // invalid, no explicit type `number` allowed
+const N3 = 3 + 3 // invalid, no expression allowed
+```
+
+* A `static` `readonly` property:
+
+```ts
+class X {
+  static readonly M1 = 3 // valid
+  static readonly M2: number = 3 // invalid
+  static readonly M3 = 3 + 3 // invalid
+}
+```
+
+
+A CTC is required in these cases.
+
+* Array size
+
+```ts
+let arr1: FixedArray<bigint, 3> = [1n, 2n, 3n]
+// `typeof` is needed since FixedArray takes a type as the array size, not a value
+let arr1: FixedArray<bigint, typeof N1> = [1n, 2n, 3n]
+let arr2: FixedArray<bigint, typeof X.M1> = [1n, 2n, 3n]
+```
+
+* Loop count in `for` statement
+
+```ts
+for(let i=0; i< 3; i++) {}
+for(let i=0; i< N1; i++) {}
+for(let i=0; i< X.M1; i++) {}
+```
+
+## Functions
+
+### Built-in Functions
+You can refer to [Built-ins](./built-ins.md) for a full list of functions and libraries built into `scryptTS`.
+
+### Whitelisted Functions
+Be default, all Javascript/TypeScript built-in functions and global variables are not allowed in `@method`s, except the following kinds.
+
+#### `console.log`
+
+`console.log` can be used for debugging purposes.
+```ts
+@method()
+add(x0: bigint, x1:bigint) : bigint {
+  console.log(x0)
+  return x0 + x1
+}
+```
+
+
+## Operators
+
+**sCrypt** is a subset of TypeScript. Only the following operators can be used directly.
+
+
+| Operator | Description |
+| :-----| :----: |
+| `+` | Addition |
+| `-` | Subtraction |
+| `*` | Multiplication |
+| `/` | Division |
+| `%` | Remainder |
+| `++` | Increment |
+| `--` | Decrement |
+| `==` | Equal to |
+| `!=` | Not equal to |
+| `===` | Same as `==` |
+| `!==` | Same as `!=` |
+| `>` | Greater than |
+| `>=` | Greater than or equal to |
+| `<` | Less than |
+| `<=` | Less than or equal to |
+| `&&` | Logical AND |
+| <code>&#124;&#124;</code> | Logical OR |
+| `!` | Logical NOT |
+| `cond ? expr1 : expr2 ` | ternary |
+| `+=` | Add and assign |
+| `-=` | Subtract and assign |
+| `*=` | Multiply and assign |
+| `/=` | Divide and assign |
+| `%=` | Assign remainder |
+
+:::note
+`**` is not supported currently.
+:::

inline-asm.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 6
+---
+
+# How To Override Methods Compiled Code
+
+In some rare cases you might want to use low level Bitcoin script to write a smart contracts method. This is usually done for optimization of the scrip size.
+To achieve this currently, you have to edit the transpiled `.scrypt` files under your projects artifacts directory.
+
+To make this a bit easier, you can re-use the code inside the `optimizations/` directory in [`scrypt-ts-lib`](https://github.com/sCrypt-Inc/scrypt-ts-lib/tree/master/optimizations).
+
+Inside this directory, there is a shell script named `apply_asm_optim.sh`. In this script, you can specify the source files where substitution with a custom bitcoin script should occur.
+
+Let's take a quick look at how this is applied in `scrypt-ts-lib` for three source files:
+
+```sh
+# BN256
+apply artifacts/src/ec/bn256.scrypt optimizations/ec/bn256
+
+# SECP256K1
+apply artifacts/src/ec/secp256k1.scrypt optimizations/ec/secp256k1
+
+# SECP256R1
+apply artifacts/src/ec/secp256r1.scrypt optimizations/ec/secp256r1
+```
+
+For instance, let's consider the content of `optimizations/ec/bn256`:
+
+```
+_addCurvePoints.asm
+doubleCurvePoint.asm
+lineFuncAdd.asm
+lineFuncDouble.asm
+modInverseBranchlessP.asm
+mulFQ12.asm
+mulLine.asm
+squareFQ12.asm
+```
+
+The name of each file corresponds to a function in the specified `.scrypt` source file (`bn256.scrypt` for this example). The files contain the actual bitcoin script in ASM format:
+
+```
+OP_3 OP_PICK 11 OP_PICK OP_MUL 12 OP_PICK OP_4 OP_PICK OP_MUL OP_ADD OP_3 OP_PICK 12 OP_PICK OP_MUL OP_5 OP_PICK 14 OP_PICK OP_MUL OP_SUB OP_7 OP_PICK 11 OP_PICK OP_MUL 12 OP_PICK OP_8 OP_PICK OP_MUL OP_ADD OP_7 OP_PICK 12 OP_PICK OP_MUL OP_9 OP_PICK 14 OP_PICK OP_MUL OP_SUB OP_3 OP_ROLL OP_ROT OP_ADD OP_ROT OP_ROT OP_ADD OP_4 OP_PICK 11 OP_PICK 13 OP_PICK OP_8 OP_PICK OP_DUP OP_3 OP_PICK OP_MUL OP_2 OP_PICK OP_5 OP_PICK OP_MUL OP_ADD OP_SWAP OP_ROT OP_MUL OP_3 OP_ROLL OP_3 ...
+```
+
+Please note that it is crucial to run `apply_asm_optim.sh` after each project build. To make this process more convenient, you can modify the build script in `package.json`:
+
+```json
+"scripts": {
+    "build": "tsc && npm run apply-optim",
+    "apply-optim": "sh optimizations/apply_asm_optim.sh",
+    ...
+```
+
+Now, after every build, the script optimizations will be applied.
+
+:::note
+Please bear in mind that modifying the contract's script code may cause inconsistencies between the on-chain and local execution (methods TS code) behavior. Once you modify the Bitcoin script, it is your responsibility to keep the two versions functionally equivalent.
+:::

installation.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 2
+---
+
+# Installation
+
+## Prerequisite
+
+1. Install `Node.js` and `NPM` on your machine by following the instructions over [here](https://nodejs.org/en/download).
+
+:::note
+Require `Node.js` version `>=16`.
+:::
+
+2. Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+## The sCrypt CLI Tool
+
+The [sCrypt CLI tool](https://github.com/sCrypt-Inc/scrypt-cli) is used to easily create, compile and publish `sCrypt` projects. The CLI provides best practice project scaffolding including dependencies such as sCrypt, a test framework ([Mocha](https://mochajs.org)), code auto-formatting ([Prettier](https://prettier.io)), linting ([ES Lint](https://eslint.org)), & more.
+
+Install it and try it out by creating a demo project:
+```sh
+npm install -g scrypt-cli
+scrypt project demo
+```
+
+:::tip
+You can also simply fork [the demo contract Repl](https://replit.com/@msinkec/scryptTS-demo) and play with the code in your browser.
+:::

oracle.md

@@ -0,0 +1,185 @@
+---
+sidebar_position: 3
+---
+
+# Tutorial 3: Oracle
+
+## Overview
+
+In this tutorial, we will go over how to build a smart contract that consumes off-chain data from an oracle. Specifically, we will implement a smart contract that lets two players bet on the price of BSV at some point in the future. It retrieves prices from an oracle.
+
+### What is an Oracle?
+A blockchain oracle is a third-party service or agent that provides external data to a blockchain network. It is a bridge between the blockchain and the external world, enabling smart contracts to access, verify, and incorporate data from outside the blockchain. This allows smart contracts to execute based on real-world events and conditions, enhancing their utility and functionality.
+
+![](../../static/img/oracle.jpeg) 
+
+[Credit: bitnovo](https://blog.bitnovo.com/en/what-is-a-blockchain-oracle/)
+
+The data supplied by oracles can include various types of information, such as stock prices, weather data, election results, and sports scores.
+
+### Rabin Signatures
+A digital signature is required to verify the authenticity and integrity of arbitrary data provided by known oracles in a smart contract. Instead of ECDSA used in Bitcoin, we use an alternative digital signature algorithm called [Rabin signatures](https://en.wikipedia.org/wiki/Rabin_signature_algorithm). This is because Rabin signature verification is orders of magnitude cheaper than ECDSA.
+We have implemented [Rabin signature](https://github.com/sCrypt-Inc/scrypt-ts-lib/blob/master/src/rabinSignature.ts) as part of the standard libraries [`scrypt-ts-lib`](https://www.npmjs.com/package/scrypt-ts-lib), which can be imported and used directly. 
+
+## Contract Properties
+
+Our contract will take signed pricing data from the [WitnessOnChain oracle](https://witnessonchain.com). Depending if the price target is reached or not, it will pay out a reward to one of the two players.
+
+There are quite a few properties which our price betting smart contract will require:
+
+```ts
+// Price target that needs to be reached.
+@prop()
+targetPrice: bigint
+
+// Symbol of the pair, e.g. "BSV_USDC"
+@prop()
+symbol: ByteString
+
+// Timestamp window in which the price target needs to be reached.
+@prop()
+timestampFrom: bigint
+@prop()
+timestampTo: bigint
+
+// Oracles Rabin public key.
+@prop()
+oraclePubKey: RabinPubKey
+
+// Addresses of both players.
+@prop()
+alicePkh: PubKeyHash
+@prop()
+bobPkh: PubKeyHash
+```
+
+Notice that the type `RabinPubKey`, which represents a Rabin public key, is not a standard type. You can import it the following way:
+
+```ts
+import { RabinPubKey } from 'scrypt-ts-lib'
+```
+
+## Public Method - `unlock`
+
+The contract will have only a single public method, namely `unlock`. As parameters, it will take the oracles signature, the signed message from the oracle, and a signature of the winner, who can unlock the funds:
+
+```ts
+@method()
+public unlock(msg: ByteString, sig: RabinSig, winnerSig: Sig) {
+    // Verify oracle signature.
+    assert(
+        RabinVerifierWOC.verifySig(msg, sig, this.oraclePubKey),
+        'Oracle sig verify failed.'
+    )
+
+    // Decode data.
+    const exchangeRate = PriceBet.parseExchangeRate(msg)
+
+    // Validate data.
+    assert(
+        exchangeRate.timestamp >= this.timestampFrom,
+        'Timestamp too early.'
+    )
+    assert(
+        exchangeRate.timestamp <= this.timestampTo,
+        'Timestamp too late.'
+    )
+    assert(exchangeRate.symbol == this.symbol, 'Wrong symbol.')
+
+    // Decide winner and check their signature.
+    const winner =
+        exchangeRate.price >= this.targetPrice
+            ? this.alicePubKey
+            : this.bobPubKey
+    assert(this.checkSig(winnerSig, winner))
+}
+```
+
+Let's walk through each part.
+
+First, we verify that the passed signature is correct. For that we use the `RabinVerifierWOC` library from the [`scrypt-ts-lib`](https://www.npmjs.com/package/scrypt-ts-lib) package
+
+```ts
+import { RabinPubKey, RabinSig, RabinVerifierWoc } from 'scrypt-ts-lib'
+```
+
+Now, we can call the `verifySig` method of the verification library:
+```ts
+// Verify oracle signature.
+assert(
+    RabinVerifierWOC.verifySig(msg, sig, this.oraclePubKey),
+    'Oracle sig verify failed.'
+)
+``` 
+The verification method requires the message signed by the oracle, the oracles signature for the message, and the oracle's public key, which we already set via the constructor.
+
+Next, we need to parse information from the chunk of data that is the signed message and assert on it. For a granular description of the message format check out the `"Exchange Rate"` section in the [WitnessOnChain API docs](https://witnessonchain.com).
+
+We need to implement the static method `parseExchangeRate` as follows:
+
+```ts
+// Parses signed message from the oracle.
+@method()
+static parseExchangeRate(msg: ByteString): ExchangeRate {
+    // 4 bytes timestamp (LE) + 8 bytes rate (LE) + 1 byte decimal + 16 bytes symbol
+    return {
+        timestamp: Utils.fromLEUnsigned(slice(msg, 0n, 4n)),
+        price: Utils.fromLEUnsigned(slice(msg, 4n, 12n)),
+        symbol: slice(msg, 13n, 29n),
+    }
+}
+```
+
+We parse out the following data:
+- `timestamp` - The time at which this exchange rate is present.
+- `price` - The exchange rate encoded as an integer -> (priceFloat * (10^decimal)).
+- `symbol` - The symbol of the token pair, e.g. `BSV_USDC`.
+
+Finally, we wrap the parsed values in a custom type, named `ExchangeRate` and return it. Here's the definition of the type:
+
+```ts
+type ExchangeRate = {
+    timestamp: bigint
+    price: bigint
+    symbol: ByteString
+}
+```
+
+Now we can validate the data. First, we check if the timestamp of the exchange rate is within our specified range that we bet on:
+
+```ts
+assert(
+    exchangeRate.timestamp >= this.timestampFrom,
+    'Timestamp too early.'
+)
+assert(
+    exchangeRate.timestamp <= this.timestampTo,
+    'Timestamp too late.'
+)
+```
+
+Additionally, we check if the exchange rate is actually for the correct token pair:
+
+```ts
+assert(exchangeRate.symbol == this.symbol, 'Wrong symbol.')
+```
+
+Lastly, upon having all the necessary information, we can choose the winner and check their signature:
+
+```ts
+const winner =
+    exchangeRate.price >= this.targetPrice
+        ? this.alicePubKey
+        : this.bobPubKey
+assert(this.checkSig(winnerSig, winner))
+```
+
+As we can see, if the target price is reached, only Alice is able to unlock the funds, and if not, then only Bob is able to do so.
+
+
+## Conclusion
+
+Congratulations! You have completed the oracle tutorial!
+
+The full code along with [tests](https://github.com/sCrypt-Inc/boilerplate/blob/master/tests/local/priceBet.test.ts) can be found in sCrypt's [boilerplate repository](https://github.com/sCrypt-Inc/boilerplate/blob/master/src/contracts/priceBet.ts).
+

overview.md

@@ -0,0 +1,53 @@
+---
+slug: /
+sidebar_position: 1
+---
+
+# Overview
+
+`sCrypt` is an `embedded Domain Specific Language` ([eDSL](https://en.wikipedia.org/wiki/Domain-specific_language#External_and_Embedded_Domain_Specific_Languages)) based on TypeScript for writing smart contracts on Bitcoin SV. `Embedded` means that it is a language inside another language. `sCrypt` is strictly a subset of TypeScript, so all `sCrypt` code is valid TypeScript, but not vice versa.
+
+We choose [TypeScript](https://www.typescriptlang.org) as the host language because it provides an easy, familiar language (JavaScript), but with type safety, making it easy to get started writing safe smart contracts. There is no need to learn a new programming language or tools, if you are already familiar with TypeScript/JavaScript.
+If you're new to TypeScript, check out this helpful [introductory video](https://www.youtube.com/watch?v=ahCwqrYpIuM).
+
+
+## How do Bitcoin Smart Contracts work?
+
+Smart contracts on Bitcoin are based on the UTXO model, which is very different from an account model like Ethereum used.
+
+### UTXO model
+
+Each bitcoin transaction consists of some inputs and outputs.
+An output contains:
+
+- The amount of bitcoins it contains.
+- bytecodes (called the `locking script`).
+
+while an input contains:
+- A reference to the previous transaction output.
+- bytecodes (the `unlocking script`).
+
+An Unspent Transaction Output (UTXO) is an output not consumed in any transaction yet. The low-level bytecode/opcode is called [Bitcoin Script](https://wiki.bitcoinsv.io/index.php/Script), which is interpreted by the [Bitcoin Virtual Machine](https://xiaohuiliu.medium.com/introduction-to-bitcoin-smart-contracts-9c0ea37dc757) (BVM).
+
+![](../static/img/utxo.jpg)
+
+In the example above, we have two transactions, each having one input (in green) and one output (in red). And the transaction on the right spends the one on the left.
+The locking script can be regarded as a boolean function `f` that specifies conditions to spend the bitcoins in the UTXO, acting as a lock (thus the name "locking").
+The unlocking script in turns provides the function arguments that makes `f` evaluates to `true`, i.e., the "key" (also called witness) needed to unlock.
+Only when the “key” in an input matches previous output’s “lock”, it can spend bitcoins contained in the output.
+
+In a regular Bitcoin payment to a [Bitcoin address](https://wiki.bitcoinsv.io/index.php/Bitcoin_address), the locking script is [Pay To Pubkey Hash (P2PKH)](https://learnmeabitcoin.com/technical/p2pkh). It checks the spender has the right private key corresponding to the address so she can produce a valid signature in the unlocking script. The expressive Script enables the locking script to specify arbitrarily more complex spending conditions than simple P2PKH, i.e., Bitcoin smart contracts.
+
+## How does `sCrypt` work?
+
+`sCrypt` is a high-level language to be compiled into [Bitcoin Script](https://wiki.bitcoinsv.io/index.php/Script). The resulting assembly-like scripts could be used as locking scripts when building transactions.
+
+## Learn `sCrypt`
+
+Jump over to the [Installation](./installation.md) section to learn how to create an `sCrypt` project. 
+
+:::tip
+You can also follow this [Youtube series](https://www.youtube.com/playlist?list=PL0Kn1t30VSpGcbwN-bcbU1-x0fRAoq-GI).
+:::
+
+Join the `#scrypt` channel on [Bitcoin SV Discord](https://discord.gg/bsv) or [Slack](https://join.slack.com/t/scryptworkspace/shared_invite/enQtNzQ1OTMyNDk1ODU3LTJmYjE5MGNmNDZhYmYxZWM4ZGY2MTczM2NiNTIxYmFhNTVjNjE5MGYwY2UwNDYxMTQyNGU2NmFkNTY5MmI1MWM) to ask questions.

scriptcontext.md

@@ -0,0 +1,161 @@
+---
+sidebar_position: 2
+---
+
+# ScriptContext
+
+In the UTXO model, the context of validating a smart contract is the UTXO containing it and the transaction spending it, including its inputs and outputs. In the following example, when the second of input of transaction `tx1` (2 inputs and 2 outputs) is spending the second output of `tx0` (3 inputs and 3 outputs), the context for the smart contract in the latter output is roughly the UTXO and `tx1` circled in red.
+![](../../static/img/scriptContext.jpg)
+
+The context only contains local information, different from account-based blockchains whose context consists of the global state of the entire blockchain (as in Ethereum). A single shared global state across all smart contracts kills scalability, since they all have to sequentially processed due to potential race conditions.
+
+This context is expressed in the `ScriptContext` interface.
+```ts
+export interface ScriptContext {
+  /** version number of [transaction]{@link https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions#General_format_of_a_Bitcoin_transaction} */
+  version: ByteString,
+  /** the specific UTXO spent by this transaction input */
+  utxo: UTXO,
+  /** double-SHA256 hash of the serialization of some/all input outpoints, see [hashPrevouts]{@link https://github.com/bitcoin-sv/bitcoin-sv/blob/master/doc/abc/replay-protected-sighash.md#hashprevouts} */
+  hashPrevouts: ByteString,
+  /** double-SHA256 hash of the serialization of some/all input sequence values, see [hashSequence]{@link https://github.com/bitcoin-sv/bitcoin-sv/blob/master/doc/abc/replay-protected-sighash.md#hashsequence} */
+  hashSequence: ByteString,
+  /** sequence number of [transaction input]{@link https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions#Format_of_a_Transaction_Input} */
+  sequence: bigint,
+  /** double-SHA256 hash of the serialization of some/all output amount with its locking script, see [hashOutputs]{@link https://github.com/bitcoin-sv/bitcoin-sv/blob/master/doc/abc/replay-protected-sighash.md#hashoutputs} */
+  hashOutputs: ByteString,
+  /** locktime of [transaction]{@link https://wiki.bitcoinsv.io/index.php/Bitcoin_Transactions#General_format_of_a_Bitcoin_transaction} */
+  locktime: bigint,
+  /** [SIGHASH flag]{@link https://wiki.bitcoinsv.io/index.php/SIGHASH_flags} used by this input */
+  sigHashType: SigHashType,
+}
+
+export interface UTXO {
+  /** locking script */
+  script: ByteString,
+  /** amount in satoshis */
+  value: bigint,
+  /** outpoint referenced by this UTXO */
+  outpoint: Outpoint,
+}
+
+export interface Outpoint {
+  /** txid of the transaction holding the output */
+  txid: ByteString,
+  /** index of the specific output */
+  outputIndex: bigint,
+}
+```
+
+The table shows the meaning of each field of the `ScriptContext` structure.
+
+| Field  | Description  |
+| ------------- | ------------- |
+| version | version of the transaction  |
+| utxo.value | value of the output spent by this input  |
+| utxo.script | locking script of the UTXO |
+| utxo.outpoint.txid | txid of the transaction being spent |
+| utxo.outpoint.outputIndex | index of the UTXO in the outputs |
+| hashPrevouts | If the `ANYONECANPAY` [SIGHASH type](#sighash-type) is not set, it's double SHA256 of the serialization of all input outpoints . Otherwise, it's a `unit256` of `0x0000......0000`. |
+| hashSequence | If none of the `ANYONECANPAY`, `SINGLE`, `NONE` [SIGHASH type](#sighash-type) is set, it's double SHA256 of the serialization of sequence of all inputs. Otherwise, it's a `unit256` of `0x0000......0000`. |
+| sequence | sequence of the input  |
+| hashOutputs | If the [SIGHASH type](#sighash-type) is neither `SINGLE` nor `NONE`, it's double SHA256 of the serialization of all outputs. If the [SIGHASH type](#sighash-type) is `SINGLE` and the input index is smaller than the number of outputs, it's the double SHA256 of the output with the same index as the input. Otherwise, it's a `unit256` of `0x0000......0000`. |
+| locktime | locktime of the transaction |
+| sigHashType| sighash type of the signature |
+
+You can directly access the context through `this.ctx` in any public `@method`.
+It can be considered additional information a public method gets when called, besides its function parameters.
+The example below accesses the [locktime](https://learnmeabitcoin.com/technical/locktime) of the spending transaction.
+
+```ts
+class CheckLockTimeVerify extends SmartContract {
+  @prop()
+  readonly matureTime: bigint // Can be timestamp or block height.
+
+  constructor(matureTime: bigint) {
+    super(...arguments)
+    this.matureTime = matureTime
+  }
+
+  @method()
+  public timelock() {
+    assert(this.ctx.locktime >= this.matureTime, "locktime too low")
+  }
+}
+```
+
+:::note
+Accessing `this.ctx` in **non-public** methods is not allowed.
+:::
+
+```ts
+@method()
+propagateState(outputs: ByteString) : boolean {
+    return this.ctx.hashOutputs == hash256(outputs); // invalid
+}
+```
+
+### Access inputs and outputs
+
+The inputs and outpus of the spending transaction are not directly included in `ScriptContext`, but their hashes/digests. To access them, we can build them first and validate they hash to the expected digest, which ensures they are actually from the spending transaction.
+The following example ensure both Alice and Bob get 1000 satoshis from the contract.
+
+```ts
+class DesignatedReceivers extends SmartContract {
+  @prop()
+  readonly alice: PubKeyHash
+
+  @prop()
+  readonly bob: PubKeyHash
+
+  constructor(alice: PubKeyHash, bob: PubKeyHash) {
+    super(...arguments)
+    this.alice = alice
+    this.bob = bob
+  }
+
+  @method()
+  public payout() {
+    const aliceOutput: ByteString = Utils.buildPublicKeyHashOutput(alice, 1000n)
+    const bobOutput: ByteString = Utils.buildPublicKeyHashOutput(bob, 1000n)
+    let outputs = aliceOutput + bobOutput
+
+    // require a change output
+    outputs += this.buildChangeOutput();
+
+    // ensure outputs are actually from the spending transaction as expected
+    assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+  }
+}
+```
+
+### SigHash Type
+
+[SigHash type](https://wiki.bitcoinsv.io/index.php/SIGHASH_flags) decides which part of the spending transaction is included in `ScriptContext`.
+![](../../static/img/sighashtypes.png)
+It defaults to `SigHash.ALL`, including all inputs and outputs. You can customize it by setting the argument of the `@method()` decorator, e.g.,
+
+```ts
+@method(SigHash.ANYONECANPAY_SINGLE)
+public increment() {
+  ...
+}
+```
+
+There are a total of 6 sigHash types to choose from:
+
+| SigHash Type | Functional Meaning |
+| ------------- | ------------- |
+| ALL | Sign all inputs and outputs |
+| NONE | Sign all inputs and no output |
+| SINGLE | Sign all inputs and the output with the same index |
+| ANYONECANPAY_ALL | Sign its own input and all outputs |
+| ANYONECANPAY_NONE | Sign its own input and no output |
+| ANYONECANPAY_SINGLE | Sign its own input and the output with the same index |
+
+
+
+
+### Debugging
+
+See [How to Debug ScriptContext Failure](../advanced/how-to-debug-scriptcontext.md)

stateful-contract.md

@@ -0,0 +1,108 @@
+---
+sidebar_position: 3
+---
+
+# Stateful Contracts
+
+## Overview
+In Bitcoin's UTXO model, a smart contract is one-off and **stateless** by default, since the UTXO containing it is destroyed after being spent. Being stateless allows it to scale easily, the same as in [HTTP](https://stackoverflow.com/questions/5836881/stateless-protocol-and-stateful-protocol) and [REST APIs](https://www.geeksforgeeks.org/restful-statelessness/).
+A smart contract can simulate state by requiring 
+the output of the spending transaction containing the same contract but with the updated state, enabled by [ScriptContext](scriptcontext.md).
+This is similar to making HTTP seem stateful by using cookies.
+
+So far, all the contracts we’ve gone through have been stateless. But often, you may want a contract to have some concept of “memory” so that it may remember information about its previous interactions. That is, we need contracts that are **stateful**.
+
+To achieve that, we divide a smart contract in the locking script of an output into two parts: code and state as shown below. The code part contains the business logic of a contract that encodes rules for state transition and must **NOT** change. State transition occurs when a transaction spends the output containing the old state and creates a new output containing the new state, while keeping the contract code intact.
+Since the new output contains the same contract code, its spending transaction must also retain the same code, otherwise it will fail. This chain of transactions can go on and on and thus a state is maintained along the chain, recursively.
+![](../../static/img/state.jpg)
+
+## Create a Stateful Contract
+
+We can create a stateful contract using the following command:
+
+```sh
+scrypt project --state counter
+```
+
+Note the `state` option is turned on.
+
+This will create a project containing a sample stateful contract named `Counter`. This contract maintains a single state: how many times it has been called since deployment.
+
+Let's take a look at the contract source file `src/contracts/counter.ts`.
+
+### Stateful properties
+As shown [before](how-to-write-a-contract.md#properties), a `@prop(true)` decorator is used to make a property part of the contract state, meaning it can be mutated when the contract gets called.
+
+```ts
+@prop(true)
+count: bigint
+```
+
+### Update states
+
+The `incrementOnChain()` method does two things:
+
+1. Call `increment` to update the state:
+
+```ts
+@method()
+increment(): void {
+    this.count++
+}
+```
+
+2. Validate the new state goes into the next UTXO containing the same contract, i.e., the state is maintained.
+
+```ts
+// make sure balance in the contract does not change
+const amount: bigint = this.ctx.utxo.value
+// outputs containing the latest state and an optional change output
+const outputs: ByteString = this.buildStateOutput(amount) + this.buildChangeOutput()
+// verify unlocking tx has the same outputs
+assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+```
+
+The built-in function `this.buildStateOutput()` creates an output containing the latest state. It takes an input: the number of satoshis in the output. We keep the satoshis unchanged in the example. The built-in functin `this.buildChangeOutput()` creates a P2PKH change output when necessary. It will calculate the change amount automatically, and use the signer's address by default.
+
+If all outputs we create in the contract hashes to `hashOutputs` in [ScriptContext](scriptcontext.md), we can be sure they are the outputs of the current transaction. Therefore, the updated state is propagated.
+
+
+The complete stateful contract is as follows:
+
+```ts
+export class Counter extends SmartContract {
+  // stateful
+  @prop(true)
+  count: bigint
+
+  constructor(count: bigint) {
+    super(...arguments)
+    this.count = count
+  }
+
+  @method()
+  public incrementOnChain() {
+    this.increment()
+
+    // make sure balance in the contract does not change
+    const amount: bigint = this.ctx.utxo.value
+    // outputs containing the latest state and an optional change output
+    const outputs: ByteString = this.buildStateOutput(amount) + this.buildChangeOutput()
+    // verify unlocking tx has the same outputs
+    assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+  }
+
+  @method()
+  increment(): void {
+    this.count++
+  }
+}
+```
+
+## Stateless vs Stateful Contracts
+
+The choice between stateless and stateful smart contracts hinges on the needs of your blockchain application.
+
+If your app needs to store persistent data on chain, a stateful smart contract is appropriate. For example, with an [auction app](../tutorials/auction.md), you want to store the highest bidder so far and how much she bids, in case you need to return the fund to her when a higher bid arrives.
+
+If your app merely validates spending conditions without retaining data, a stateless smart contract is desirable. An example is a simple transfer using signature and public key in a [P2PKH contract](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#method-with-signatures).

tic-tac-toe.md

@@ -0,0 +1,321 @@
+---
+sidebar_position: 4
+---
+
+# Tutorial 4: Tic Tac Toe
+
+## Overview
+In this tutorial, we will go over how to use sCrypt to build a Tic-Tac-Toe Contract on Bitcoin.
+
+It is initialized with the Bitcoin public key of two players (Alice and Bob respectively). They each bet the same amount and lock it into the contract. The winner takes all bitcoins locked in the contract. If no one wins and there is a draw, the two players can each withdraw half of the money.
+
+## Contract Properties
+
+Use `@prop` decorator to mark any property that intends to be stored on chain. This decorator accepts a boolean parameter. By default, it is set to `false`, meaning the property cannot be changed after the contract is deployed. If it is `true`, the property is a so-called [stateful](../how-to-write-a-contract/stateful-contract.md) property and its value can be updated in subsequent contract calls.
+
+The tic-tac-toe contract supports two players and their public keys need to be saved. It contains the following contract properties:
+
+- Two stateless properties `alice` and `bob`, both of which are `PubKey` type.
+- Two stateful properties:
+    * `is_alice_turn`: a `boolean`. It represents whether it is `alice`'s turn to play.
+    * `board`: a fixed-size array `FixedArray<bigint, 9>` with a size of `9`. It represents the state of every square in the board.
+- Three constants:
+    * `EMPTY`, type `bigint`, value `0n`. It means that a square in the board is empty
+    * `ALICE`, type `bigint`, value `1n`. Alice places symbol `X` in a square.
+    * `BOB`, type `bigint`, value `2n`. Bob places symbol `O` in a square.
+
+```ts
+@prop()
+alice: PubKey; // alice's public Key
+@prop()
+bob: PubKey; // bob's public Key
+
+@prop(true)
+is_alice_turn: boolean; // stateful property, it represents whether it is `alice`'s turn to play.
+
+@prop(true)
+board: FixedArray<bigint, 9>; // stateful property, a fixed-size array, it represents the state of every square in the board.
+
+@prop()
+static readonly EMPTY: bigint = 0n; // static property, it means that the a square in the board is empty
+@prop()
+static readonly ALICE: bigint = 1n; // static property, it means that alice places symbol `X` in a square.
+@prop()
+static readonly BOB: bigint = 2n; // static property, it means that bob places symbol `O` in a square.
+```
+
+## Constructor
+
+Initialize all non-static properties in the constructor. Specifically, the entire board is empty at first.
+
+```ts
+constructor(alice: PubKey, bob: PubKey) {
+    super(...arguments);
+    this.alice = alice;
+    this.bob = bob;
+    this.is_alice_turn = true;
+    this.board = fill(TicTacToe.EMPTY, 9);
+}
+```
+
+## Public Methods
+
+A public `@method` can be called from an external transaction. The call succeeds if it runs to completion without violating any conditions in `assert()`. 
+
+The `TicTacToe` contract have a public `@method` called `move()` with `2` parameters:
+
+```ts
+/**
+ * play the game by calling move()
+ * @param n which square to place the symbol
+ * @param sig a player's signature
+ */
+@method()
+public move(n: bigint, sig: Sig) {
+    assert(n >= 0n && n < 9n);
+}
+```
+
+Alice and Bob each locks X bitcoins in a UTXO containing contract `TicTacToe`. Next, they alternately play the game by calling `move()`.
+
+### Signature Verification
+
+Once the game contract is deployed, anyone can view and potentially interact with it. We need a authentication mechanism to ensure only the desired player can update the contract if it's their turn. This is achieved using ditigal signatures.
+
+`this.checkSig()` is used to verify a signature against a public key. Use it to verify the `sig` parameter against the desired player in `move()`, identified by their public key stored in the contract's properties.
+
+```ts
+// check signature `sig`
+let player: PubKey = this.is_alice_turn ? this.alice : this.bob;
+assert(this.checkSig(sig, player), `checkSig failed, pubkey: ${player}`);
+```
+
+## Non-Public Methods
+
+Without a `public` modifier, a `@method` is internal and cannot be directly called from an external transaction.
+
+The `TicTacToe` contract have two **Non-Public** methods:
+
+- `won()` : iterate over the `lines` array to check if a player has won the game. returns `boolean` type.
+- `full()` : traverse all the squares of the board to check if all squares of the board have symbols. returns `boolean` type.
+
+
+```ts
+@method()
+won(play: bigint) : boolean {
+    let lines: FixedArray<FixedArray<bigint, 3>, 8> = [
+        [0n, 1n, 2n],
+        [3n, 4n, 5n],
+        [6n, 7n, 8n],
+        [0n, 3n, 6n],
+        [1n, 4n, 7n],
+        [2n, 5n, 8n],
+        [0n, 4n, 8n],
+        [2n, 4n, 6n]
+    ];
+
+    let anyLine = false;
+
+    for (let i = 0; i < 8; i++) {
+        let line = true;
+        for (let j = 0; j < 3; j++) {
+            line = line && this.board[Number(lines[i][j])] === play;
+        }
+
+        anyLine = anyLine || line;
+    }
+
+    return anyLine;
+}
+
+@method()
+full() : boolean {
+    let full = true;
+    for (let i = 0; i < 9; i++) {
+        full = full && this.board[i] !== TicTacToe.EMPTY;
+    }
+    return full;
+}
+```
+
+## Maintain Game State
+
+We can directly access the [ScriptContext](../how-to-write-a-contract/scriptcontext.md) through `this.ctx` in the public `@method` `move()` to maintain game state. It can be considered additional information a public method gets when called, besides its function parameters.
+
+Contract maintenance state consists of the following three steps:
+
+### Step 1
+
+Update the stateful properties in public `@method`.
+
+A player call `move()` to places the symbol in the board. We should update the stateful properties `board` and `is_alice_turn` in the `move()` `@method`: 
+
+```ts
+assert(this.board[Number(n)] === TicTacToe.EMPTY, `board at position ${n} is not empty: ${this.board[Number(n)]}`);
+let play = this.is_alice_turn ? TicTacToe.ALICE : TicTacToe.BOB;
+// update stateful properties to make the move
+this.board[Number(n)] = play;   // Number() converts a bigint to a number
+this.is_alice_turn = !this.is_alice_turn;
+```
+
+### Step 2
+
+When you are ready to pass the new state onto the output[s] in the current spending transaction, simply call a built-in function `this.buildStateOutput()` to create an output containing the new state. It takes an input: the number of satoshis in the output. We keep the satoshis unchanged in the example.
+
+```ts
+let output = this.buildStateOutput(this.ctx.utxo.value);
+```
+
+
+
+#### Build outputs in public `@method`
+
+`TicTacToe` can contain the following three types of output during execution:
+
+1. The game is not over: a output containing the new state and a change output
+2. A player wins the game: a `P2PKH` output that pays the winner, and a change output.
+3. A draw: two `P2PKH` outputs that split the contract-locked bets equally between the players and a change output.
+
+The `P2PKH` output can be built using `Utils.buildPublicKeyHashOutput(pkh: PubKeyHash, amount: bigint)`. The [change output](https://wiki.bitcoinsv.io/index.php/Change) can be built using `this.buildChangeOutput()`.
+
+
+```ts
+// build the transation outputs
+let outputs = toByteString('');
+if (this.won(play)) {
+    outputs = Utils.buildPublicKeyHashOutput(hash160(player), this.ctx.utxo.value);
+}
+else if (this.full()) {
+    const halfAmount = this.ctx.utxo.value / 2n;
+    const aliceOutput = Utils.buildPublicKeyHashOutput(hash160(this.alice), halfAmount);
+    const bobOutput = Utils.buildPublicKeyHashOutput(hash160(this.bob), halfAmount);
+    outputs = aliceOutput + bobOutput;
+}
+else {
+    // build a output that contains latest contract state.
+    outputs = this.buildStateOutput(this.ctx.utxo.value);
+}
+
+outputs += this.buildChangeOutput();
+
+```
+
+### Step 3
+
+Make sure that the output of the current transaction must contain this incremented new state. If all outputs (only a single output here) we create in the contract hashes to `hashOutputs` in `ScriptContext`, we can be sure they are the outputs of the current transaction. Therefore, the updated state is propagated.
+
+```ts
+// verify current tx has this single output
+assert(this.ctx.hashOutputs == hash256(outputs), 'hashOutputs mismatch')
+```
+
+# Conclusion
+
+Congratulations, you have completed the `TicTacToe` contract!
+
+The [final complete code](https://github.com/sCrypt-Inc/tic-tac-toe/blob/main/src/contracts/tictactoe.ts) is as follows:
+
+```ts
+export class TicTacToe extends SmartContract {
+    @prop()
+    alice: PubKey;
+    @prop()
+    bob: PubKey;
+
+    @prop(true)
+    is_alice_turn: boolean;
+
+    @prop(true)
+    board: FixedArray<bigint, 9>;
+
+    @prop()
+    static readonly EMPTY: bigint = 0n;
+    @prop()
+    static readonly ALICE: bigint = 1n;
+    @prop()
+    static readonly BOB: bigint = 2n;
+
+    constructor(alice: PubKey, bob: PubKey) {
+        super(...arguments)
+        this.alice = alice;
+        this.bob = bob;
+        this.is_alice_turn = true;
+        this.board = fill(TicTacToe.EMPTY, 9);
+    }
+
+    @method()
+    public move(n: bigint, sig: Sig) {
+        // check position `n`
+        assert(n >= 0n && n < 9n);
+        // check signature `sig`
+        let player: PubKey = this.is_alice_turn ? this.alice : this.bob;
+        assert(this.checkSig(sig, player), `checkSig failed, pubkey: ${player}`);
+        // update stateful properties to make the move
+        assert(this.board[Number(n)] === TicTacToe.EMPTY, `board at position ${n} is not empty: ${this.board[Number(n)]}`);
+        let play = this.is_alice_turn ? TicTacToe.ALICE : TicTacToe.BOB;
+        this.board[Number(n)] = play;
+        this.is_alice_turn = !this.is_alice_turn;
+
+        // build the transation outputs
+        let outputs = toByteString('');
+        if (this.won(play)) {
+            outputs = Utils.buildPublicKeyHashOutput(hash160(player), this.ctx.utxo.value);
+        }
+        else if (this.full()) {
+            const halfAmount = this.ctx.utxo.value / 2n;
+            const aliceOutput = Utils.buildPublicKeyHashOutput(hash160(this.alice), halfAmount);
+            const bobOutput = Utils.buildPublicKeyHashOutput(hash160(this.bob), halfAmount);
+            outputs = aliceOutput + bobOutput;
+        }
+        else {
+            // build a output that contains latest contract state.
+            outputs = this.buildStateOutput(this.ctx.utxo.value);
+        }
+
+        outputs += this.buildChangeOutput();
+
+        // make sure the transaction contains the expected outputs built above
+        assert(this.ctx.hashOutputs === hash256(outputs), "check hashOutputs failed");
+    }
+
+    @method()
+    won(play: bigint): boolean {
+        let lines: FixedArray<FixedArray<bigint, 3>, 8> = [
+            [0n, 1n, 2n],
+            [3n, 4n, 5n],
+            [6n, 7n, 8n],
+            [0n, 3n, 6n],
+            [1n, 4n, 7n],
+            [2n, 5n, 8n],
+            [0n, 4n, 8n],
+            [2n, 4n, 6n]
+        ];
+
+        let anyLine = false;
+
+        for (let i = 0; i < 8; i++) {
+            let line = true;
+            for (let j = 0; j < 3; j++) {
+                line = line && this.board[Number(lines[i][j])] === play;
+            }
+
+            anyLine = anyLine || line;
+        }
+
+        return anyLine;
+    }
+
+    @method()
+    full(): boolean {
+        let full = true;
+        for (let i = 0; i < 9; i++) {
+            full = full && this.board[i] !== TicTacToe.EMPTY;
+        }
+        return full;
+    }
+
+}
+
+```
+
+But no dApp is complete if users cannot interact with it. Go [here](../how-to-integrate-a-frontend/how-to-integrate-a-frontend.md) to see how to add a front end to it.

voting.md

@@ -0,0 +1,706 @@
+---
+sidebar_position: 6
+---
+
+# Tutorial 6: Voting
+
+## Overview
+
+In this tutorial, we will go over how to use sCrypt to build a full-stack voting dApp on Bitcoin, including the smart contract and an interactive front-end.
+
+![](../../static/img/voting.gif)
+
+On the web page, you can see the candidate list. Clicking the like button will cast one vote for the corresponding candidate. This will prompt the wallet to ask for a user's approval. A transaction calling the contract will be sent after her approval.
+
+First, we will write and deploy the smart contract step by step. Afterward, we will build a front-end with React that allows users to cast votes and thus interact with the contract.
+
+## Contract
+
+### Properties
+
+For each candidate, there are two properties we need to store in the contract: her name and her votes received so far.
+
+We define a type alias of `ByteString` to represent a candidate name.
+
+```ts
+export type Name = ByteString
+```
+
+We define a struct to represent a candidate.
+
+```ts
+export type Candidate = {
+  name: Name
+  votesReceived: bigint
+}
+```
+
+We use a `FixedArray` to store the list of candidates, which we alias as type `Candidates`.
+Since candidates' vote counts can be updated, we mark it [stateful](../how-to-write-a-contract/stateful-contract.md#stateful-properties) by setting `@prop(true)`.
+
+```ts
+export const N = 2
+export type Candidates = FixedArray<Candidate, typeof N>
+
+export class Voting extends SmartContract {  
+  @prop(true)
+  candidates: Candidates
+  // ...
+}
+```
+
+### Constructor
+
+Initialize all the `@prop` properties in the constructor. Note that we only need to pass the candidate names in the argument, because the votes they received would be all 0 at the beginning.
+
+```ts
+constructor(names: FixedArray<Name, typeof N>) {
+  super(...arguments)
+  // initialize fixed array
+  this.candidates = fill({
+      name: toByteString(''),
+      votesReceived: 0n
+  }, N)
+  // set names and set votes they received to 0
+  for (let i = 0; i < N; i++) {
+    this.candidates[i] = { name: names[i], votesReceived: 0n }
+  }
+}
+```
+
+### Methods
+
+The only way to interact with this contract is to vote for one candidate in the list, so we will have only 1 **public** method `vote`. It takes only 1 parameter: the name of the candidate you want to vote for.
+
+```ts
+@method()
+public vote(name: Name) {
+  // 1) change contract state: add one vote to `candidate` in the list
+  // 2) propogate the state
+}
+```
+
+We can simply use a `for` loop to implement this: find the corresponding candidate in the list by name, then increment its vote by one. We implement this in a helper method `increaseVotesReceived`.
+
+```ts
+// cast one vote to a candidate
+@method()
+increaseVotesReceived(name: Name): void {
+  for (let i = 0; i < N; i++) {
+    if (this.candidates[i].name === name) {
+      this.candidates[i].votesReceived++
+    }
+  }
+}
+```
+
+After we increment the candidate's votes and update the contract state, we make sure the new state is maintained in the spending transaction's output [as usual](../how-to-write-a-contract/stateful-contract.md#update-states). Another output is added if change is needed.
+
+```ts
+let outputs: ByteString = this.buildStateOutput(this.ctx.utxo.value)
+outputs += this.buildChangeOutput()
+assert(this.ctx.hashOutputs === hash256(outputs), 'hashOutputs mismatch')
+```
+
+The public function `vote` is now finished.
+
+```ts
+@method()
+public vote(name: Name) {
+  // change contract state: add one vote to `candidate` in the list
+  this.increaseVotesReceived(name)
+  
+  // restrict tx outputs
+  // to contain the latest state with the same balance
+  let outputs: ByteString = this.buildStateOutput(this.ctx.utxo.value)
+  // to contain the change output when necessary
+  outputs += this.buildChangeOutput()
+
+  assert(this.ctx.hashOutputs === hash256(outputs), 'hashOutputs mismatch')
+}
+```
+
+### Final Code
+
+You have completed the `Voting` contract! The [final complete code](https://github.com/sCrypt-Inc/voting/blob/master/src/contracts/voting.ts) is as follows:
+
+```ts
+import { assert, ByteString, hash256, method, prop, SmartContract, FixedArray, fill, toByteString } from 'scrypt-ts'
+
+export type Name = ByteString
+
+export type Candidate = {
+    name: Name
+    votesReceived: bigint
+}
+
+export const N = 2
+
+export type Candidates = FixedArray<Candidate, typeof N>
+
+export class Voting extends SmartContract {
+    @prop(true)
+    candidates: Candidates
+
+    constructor(names: FixedArray<Name, typeof N>) {
+        super(...arguments)
+        // initialize fixed array
+        this.candidates = fill({
+            name: toByteString(''),
+            votesReceived: 0n,
+        }, N)
+        // set names and set votes they received to 0
+        for (let i = 0; i < N; i++) {
+            this.candidates[i] = {
+                name: names[i],
+                votesReceived: 0n,
+            }
+        }
+    }
+
+    /**
+     * vote for a candidate
+     * @param name candidate's name
+     */
+    @method()
+    public vote(name: Name) {
+        // change contract state: add one vote to `candidate` in the list
+        this.increaseVotesReceived(name)
+        // output containing the latest state and the same balance
+        let outputs: ByteString = this.buildStateOutput(this.ctx.utxo.value)
+        outputs += this.buildChangeOutput()
+        assert(this.ctx.hashOutputs === hash256(outputs), 'hashOutputs mismatch')
+    }
+
+    @method()
+    increaseVotesReceived(name: Name): void {
+        for (let i = 0; i < N; i++) {
+            if (this.candidates[i].name === name) {
+                this.candidates[i].votesReceived++
+            }
+        }
+    }
+}
+```
+
+## Frontend
+
+We will add a frontend to the voting smart contract according to [this guide](../how-to-integrate-a-frontend/how-to-integrate-a-frontend.md).
+
+### Setup Project
+
+The front-end will be created using [Create React App](https://create-react-app.dev/).
+
+```bash
+npx create-react-app voting --template typescript
+```
+
+### Install the sCrypt SDK
+
+The sCrypt SDK enables you to easily compile, test, deploy, and call contracts.
+
+Use the `scrypt-cli` command line to install the SDK.
+
+```bash
+cd voting
+npx scrypt-cli init
+```
+
+This command will create a contract file at `src\contracts\voting.ts`, replace the content of the file with the contract written [above](#final-code).
+
+### Compile Contract
+
+Compile the contract with the following command: 
+
+```bash
+npx scrypt-cli compile
+```
+
+This command will generate a contract artifact file at `artifacts\src\contracts\voting.json`.
+
+### Contract Deployment
+
+After [installing the sCrypt SDK](#install-the-scrypt-sdk), you will have a script `deploy.ts` in the project directory, which can be used to deploy our `Voting` contract after some minor modifications.
+
+```ts
+import { Name, Voting, N } from './src/contracts/voting'
+import { bsv, TestWallet, DefaultProvider, toByteString, FixedArray } from 'scrypt-ts'
+
+import * as dotenv from 'dotenv'
+
+// Load the .env file
+dotenv.config()
+
+// Read the private key from the .env file.
+// The default private key inside the .env file is meant to be used for the Bitcoin testnet.
+// See https://scrypt.io/docs/bitcoin-basics/bsv/#private-keys
+const privateKey = bsv.PrivateKey.fromWIF(process.env.PRIVATE_KEY || '')
+
+// Prepare signer. 
+// See https://scrypt.io/docs/how-to-deploy-and-call-a-contract/#prepare-a-signer-and-provider
+const signer = new TestWallet(privateKey, new DefaultProvider({
+    network: bsv.Networks.testnet
+}))
+
+async function main() {
+    await Voting.compile()
+
+    const candidateNames: FixedArray<Name, typeof N> = [
+        toByteString('iPhone', true),
+        toByteString('Android', true)
+    ]
+
+    const instance = new Voting(
+        candidateNames
+    )
+
+    // Connect to a signer.
+    await instance.connect(signer)
+
+    // Contract deployment.
+    const amount = 1
+    const deployTx = await instance.deploy(amount)
+    console.log('Voting contract deployed: ', deployTx.id)
+}
+
+main()
+```
+
+Before deploying the contract, we need to create a `.env` file and save your private key in the `PRIVATE_KEY` environment variable.
+
+```
+PRIVATE_KEY=xxxxx
+```
+
+If you don't have a private key, you can follow [this guide](../../how-to-deploy-and-call-a-contract/faucet) to generate one using Sensilet wallet, then fund the private key's address with our [faucet](https://scrypt.io/faucet/).
+
+Run the following command to deploy the contract.
+
+```bash
+npm run deploy:contract
+```
+
+After success, you will see an output similar to the following:
+
+![](../../static/img/deploy-output.png)
+
+#### Contract ID
+
+Your can get the deployed contract's ID: the TXID and the output index where the contract is located.
+```js
+const contract_id = {
+  /** the deployment transaction id */
+  txId: "6751b645e1579e8e6201e3c59b900ad58e59868aa5e4ee89359d3f8ca1d66c8a",
+  /** the output index */
+  outputIndex: 0,
+};
+```
+
+### Verify
+
+After a successful deployment of a smart contract, you can verify the deployed contract script:
+
+```sh
+npm run verify:contract
+```
+
+Upon execution, the designated contract code undergoes verification on sCrypt's servers. If successful, the outcome will be [displayed on WoC](https://test.whatsonchain.com/script/cecb4f8799913df3e5af50bc81a24e3fef3216a92452d27cd97dcd7ccbce1f1b), under the "sCrypt" tab. See the ["How to Verify a Contract"](../how-to-verify-a-contract.md) page for more details.
+
+### Load Contract Artifact
+
+Before writing the front-end code, we need to load the contract artifact in `src\index.tsx`.
+
+```ts
+import { Voting } from './contracts/voting';
+var artifact = require('../artifacts/src/contracts/voting.json');
+Voting.loadArtifact(artifact);
+```
+
+### Integrate Wallet
+
+Use `requestAuth` method of `signer` to request access to the wallet.
+
+```ts
+// request authentication
+const { isAuthenticated, error } = await signer.requestAuth();
+if (!isAuthenticated) {
+    // something went wrong, throw an Error with `error` message
+    throw new Error(error);
+}
+
+// authenticated
+// ...
+```
+
+### Integrate sCrypt Service
+
+To interacte with the voting contract, we need to create a contract instance representing the latest state of the contract on chain. When both Alice and Bob vote on the webpage, we need to ensure that their contract instances are always up to date. After Alice votes, we have to notify Bob that the state of the contract has changed and synchronize his local contract instance to the latest state on chain.
+
+Fortunately,`sCrypt` provides such infrastructure service, which abstracts away all the common complexities of communicating with the blockchain, so we do not have to track the contract state, which could be computationally demanding as blockchain grows. We can instead focus on our application's business logic.
+
+To use it, we first have to initialize it according to [this guide](../advanced/how-to-integrate-scrypt-service.md).
+
+```ts
+Scrypt.init({
+  apiKey: 'YOUR_API_KEY',
+  network: bsv.Networks.testnet
+})
+```
+
+### Connect Signer to `ScryptProvider`
+
+It's required to connect your signer to `ScryptProvider` when using sCrypt service.
+
+```ts
+const provider = new ScryptProvider();
+const signer = new SensiletSigner(provider);
+
+signerRef.current = signer;
+```
+
+### Fetch Latest Contract Instance
+
+We can fetch a contract's latest instance by calling the `Scrypt.contractApi.getLatestInstance()` using its [contract ID](#contract-id). With this instance, we can easily read a contract's properties to display to the user on the webpage, or update the contract state by calling its public method as [before](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call) when the user votes for a candidate.
+
+```ts
+function App() {
+  const [votingContract, setContract] = useState<Voting>();
+  const [error, setError] = React.useState("");
+  
+  // ...
+
+  async function fetchContract() {
+    try {
+      const instance = await Scrypt.contractApi.getLatestInstance(
+        Voting,
+        contract_id
+      );
+      setContract(instance);
+    } catch (error: any) {
+      console.error("fetchContract error: ", error);
+      setError(error.message);
+    }
+  }
+    
+  // ...
+}
+```
+
+### Read contract state
+
+With the contract instance, we can read its lastest state and render it.
+
+```ts
+function byteString2utf8(b: ByteString) {
+  return Buffer.from(b, "hex").toString("utf8");
+}
+
+function App() {
+  // ...
+
+  return (
+    <div className="App">
+      <header className="App-header">
+        <h2>What's your favorite phone?</h2>
+      </header>
+      <TableContainer
+        component={Paper}
+        variant="outlined"
+        style={{ width: 1200, height: "80vh", margin: "auto" }}
+      >
+        <Table>
+          <TableHead>
+            <TableRow>
+              <TableCell align="center">Iphone</TableCell>
+              <TableCell align="center">Android</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            <TableRow>
+              <TableCell align="center">
+                <Box>
+                  <Box
+                    sx={{
+                      height: 200,
+                    }}
+                    component="img"
+                    alt={"iphone"}
+                    src={`${process.env.PUBLIC_URL}/${"iphone"}.png`}
+                  />
+                </Box>
+              </TableCell>
+              <TableCell align="center">
+                <Box>
+                  <Box
+                    sx={{
+                      height: 200,
+                    }}
+                    component="img"
+                    alt={"android"}
+                    src={`${process.env.PUBLIC_URL}/${"android"}.png`}
+                  />
+                </Box>
+              </TableCell>
+            </TableRow>
+            <TableRow>
+              <TableCell align="center">
+                <Box>
+                  <Typography variant={"h1"} >
+                    {votingContract?.candidates[0].votesReceived.toString()}
+                  </Typography>
+                  <Button
+                    variant="text"
+                    onClick={voting}
+                    name={votingContract?.candidates[0].name}
+                  >
+                    👍
+                  </Button>
+                </Box>
+              </TableCell>
+
+              <TableCell align="center">
+              <Divider orientation="vertical" flexItem />
+                <Box>
+                  <Typography variant={"h1"}>
+                    {votingContract?.candidates[1].votesReceived.toString()}
+                  </Typography>
+                  <Button
+                    variant="text"
+                    onClick={voting}
+                    name={votingContract?.candidates[1].name}
+                  >
+                    👍
+                  </Button>
+                </Box>
+              </TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      </TableContainer>
+      <Footer />
+      <Snackbar
+        open={error !== ""}
+        autoHideDuration={6000}
+        onClose={handleClose}
+      >
+        <Alert severity="error">{error}</Alert>
+      </Snackbar>
+
+      <Snackbar
+        open={success.candidate !== "" && success.txId !== ""}
+        autoHideDuration={6000}
+        onClose={handleSuccessClose}
+      >
+        <Alert severity="success">
+          {" "}
+          <Link
+            href={`https://test.whatsonchain.com/tx/${success.txId}`}
+            target="_blank"
+            rel="noreferrer"
+          >
+            {`"${byteString2utf8(success.candidate)}" got one vote,  tx: ${
+              success.txId
+            }`}
+          </Link>
+        </Alert>
+      </Snackbar>
+    </div>
+  );
+}
+```
+
+### Update Contract State
+
+To update the contract's state, we need to call its public method. We create a function `voting()` to handle the voting event triggered by a user.
+
+Calling a contract public method is [the same as before](../how-to-deploy-and-call-a-contract/how-to-deploy-and-call-a-contract.md#contract-call).
+
+```ts
+async function voting(e: any) {
+  // ...
+
+  const signer = signerRef.current as SensiletSigner;
+
+  if (votingContract && signer) {
+    const { isAuthenticated, error } = await signer.requestAuth();
+    if (!isAuthenticated) {
+      throw new Error(error);
+    }
+
+    await votingContract.connect(signer);
+
+    // create the next instance from the current
+    const nextInstance = votingContract.next();
+
+    const candidateName = e.target.name;
+
+    // update state
+    nextInstance.increaseVotesReceived(candidateName);
+
+    // call the method of current instance to apply the updates on chain
+    votingContract.methods
+      .vote(candidateName, {
+        next: {
+          instance: nextInstance,
+          balance: votingContract.balance,
+        },
+      })
+      .then((result) => {
+        console.log(`Voting call tx: ${result.tx.id}`);
+      })
+      .catch((e) => {
+        setError(e.message);
+        fetchContract();
+        console.error("call error: ", e);
+      });
+  }
+}
+```
+
+If successful, you will see the following log in the `console`:
+
+```
+Voting call tx: fc8b3d03b8fa7469d66a165b017fe941fa8ab59c0979457cef2b6415d659e3f7
+```
+
+### Subscribe to Contract Event
+
+So far, we have a fully working app. However, there is a slight problem. When Alice clicks on the like button for a candadate in her browser, the candidate's vote count in Bob's browser does not increase, unless he manually refreshes. 
+We need a way to listen to contract event. 
+
+We call `Scrypt.contractApi.subscribe(options: SubscribeOptions<T>, cb: (e: ContractCalledEvent<T>) => void): SubScription` to subscribe to events that the contract has been called. When a contract gets called and updated, we refresh the UI in real time, re-render all the content on the page and show the updated vote count.
+
+The subscribe function takes 2 parameters:
+
+1. `options: SubscribeOptions<T>`: it includes a contract class, a contract ID, and a optional list of method names monitored.
+
+```ts
+interface SubscribeOptions<T> {
+  clazz: new (...args: any) => T;
+  id: ContractId;
+  methodNames?: Array<string>;
+}
+```
+
+If `methodNames` is set, you will be notified only when public functions in the list are called. Otherwise, you will be notified when ANY public function is called.
+
+2. `callback: (event: ContractCalledEvent<T>) => void`: a callback funciton upon receiving notifications. 
+
+`ContractCalledEvent<T>` contains the relevant information when the contract is called, such as the public function name and function arguments when the call occurs.
+
+```ts
+export interface ContractCalledEvent<T> {
+  /** name of public function */
+  methodName: string;
+  /** public function arguments */
+  args: SupportedParamType[];
+  /** transaction where contract is called from */
+  tx: bsv.Transaction;
+  /**
+   * If a stateful contract is called, `nexts` contains the contract instance containing the new state generated by this call.
+   * If a stateless contract is called, `nexts` is empty.
+   */
+  nexts: Array<T>;
+}
+```
+
+The code to subscribe to contract events is as follows.
+
+```ts
+useEffect(() => {
+  const provider = new ScryptProvider();
+  const signer = new SensiletSigner(provider);
+
+  signerRef.current = signer;
+
+  fetchContract();
+
+  // subscribe by contract_id
+  const subscription = Scrypt.contractApi.subscribe({
+    clazz: Voting,
+    id: contract_id
+  }, (event: ContractCalledEvent<Voting>) => {
+    // update the contract instance 
+    setSuccess({
+      txId: event.tx.id,
+      candidate: event.args[0] as ByteString,
+    });
+    setContract(event.nexts[0]);
+  });
+
+  return () => {
+    // unsubscribe
+    subscription.unsubscribe();
+  };
+}, []);
+```
+
+### Deploy to GitHub Pages
+
+After pushing the frontend project to your GitHub account, it's easy to [publish a website with GitHub Pages](https://create-react-app.dev/docs/deployment/#github-pages), so that users can interact with your dApp with the browser.
+
+#### Step 1. Add `homepage` to `package.json`
+
+Open your `package.json` and add a `homepage` field for your project.
+
+```json
+{
+  "name": "voting",
+  "homepage": "https://[YOUR-GITHUB-USERNAME].github.io/[YOUR-REPO-NAME]"
+  ...
+}
+```
+
+![](../../static/img/voting-homepage.png)
+
+For example, our demo repo is at https://github.com/sCrypt-Inc/voting, so we set
+
+```
+https://sCrypt-Inc.github.io/voting
+```
+
+as the homepage, where `sCrypt-Inc` is our GitHub username, and `voting` is the repo name.
+
+#### Step 2. Install `gh-pages` and add `scripts` in `package.json`
+
+Run the following command to install the dependency.
+
+```sh
+npm install --save gh-pages
+```
+
+Then add two scripts in `package.json`.
+
+```json
+"scripts": {
+  "predeploy": "npm run build",
+  "deploy": "gh-pages -d build",
+  ...
+},
+```
+
+![](../../static/img/voting-scripts.png)
+
+:::note
+The `predeploy` script will run automatically before `deploy` is run.
+:::
+
+#### Step 3. Deploy the site
+
+Run the following command to deploy the website.
+
+```sh
+npm run deploy
+```
+
+#### Step 4. Update GitHub project settings
+
+After running the `deploy` script, don't forget to update your GitHub project settings to use `gh-pages` branch. Go to `Settings --> Code and automation/Pages`, and select `gh-pages` as the branch used by the GitHub Pages site.
+
+![](../../static/img/gh-pages.png)
+
+### Conclusion
+
+Congratulations! You have successfully completed a fullstack voting dapp fully on Bitcoin.
+
+The repo is [here](https://github.com/sCrypt-Inc/voting). And an online example is [here](http://classic.scrypt.io/voting).

zkp.md

@@ -0,0 +1,305 @@
+---
+sidebar_position: 5
+---
+
+# Tutorial 5: Zero Knowledge Proofs
+
+## Overview 
+
+In this tutorial we will go over how to create a zero-knowledge proof (ZKP) and verify it on Bitcoin using sCrypt.
+
+### What are zk-SNARKS?
+
+SNARK (zero-knowledge Succinct Non-interactive ARguments of Knowledge) is a type of ZKP that is amenable for blockchains. The generated proof is “succinct” and “non-interactive”: a proof is only a few hundred bytes and can be verified in constant time and within a few milliseconds, without needing to ask additional questions of the prover. Together, these properties make zk-SNARK especially suitable for blockchains, where on-chain storage and computation can be expensive and senders often go offline after sending a transaction. 
+
+A proof is constructed off-chain by a prover who generates the proof using a secret input (often referred to as the "witness") and a public input. The prover can then use this proof as an input for an sCrypt smart contract, which can verify the validity of the proof using a verification key and the public input.
+
+![](../../static/img/zksnark-verifier.png)
+
+[Credit: altoros](https://www.altoros.com/blog/securing-a-blockchain-with-a-noninteractive-zero-knowledge-proof/)
+
+
+There are many tools for creating such proofs, [ZoKrates](https://github.com/sCrypt-Inc/zokrates) and [SnarkJS](https://github.com/sCrypt-Inc/snarkjs) are among the most popular. 
+
+In this example we will use ZoKrates. It provides a python-like higher-level language for developers to code the computational problem they want to prove.
+
+For a more comprehensive explanation of zk-SNARKS and how they work, we recommend reading [this blog post](https://xiaohuiliu.medium.com/zk-snarks-on-bitcoin-239d96d182bd).
+
+## Install ZoKrates
+
+Run the following command to install [released binaries](https://github.com/sCrypt-Inc/zokrates/releases):
+
+```sh
+curl -Ls https://scrypt.io/scripts/setup-zokrates.sh | sh -s -
+```
+
+or build from source:
+
+```sh
+git clone https://github.com/sCrypt-Inc/zokrates
+cd ZoKrates
+cargo +nightly build -p zokrates_cli --release
+cd target/release
+```
+
+## ZoKrates Workflow
+
+### 1. Design a circuit
+
+Create a new ZoKrates file named `factor.zok` with the following content:
+
+```python
+// p, q are the factors of n
+def main(private field p, private field q, field n) {
+    assert(p * q == n);
+    assert(p > 1);
+    assert(q > 1);
+    return;
+}
+```
+
+This simple circuit/program proves one knows a factorization of an integer `n` into two integers, without revealing the factors. The circuit has two private inputs named `p` and `q` and one public input named `n`.
+
+
+### 2. Compile the circuit
+
+Compile the circuit with the following command:
+
+```sh
+zokrates compile -i factor.zok
+```
+
+This generates two files that encode the circuit in binary and human-readable format.
+
+### 3. Setup
+
+This generates a proving key and a verification key for this circuit.
+
+```sh
+zokrates setup
+```
+
+### 4. Calculate a witness
+
+A proof attests that a prover knows some secret/private information that satisfies the original program. This secret information is called witness. In the following example, `7` and `13` are the witnesses, as they are factors of `91`.
+
+```sh
+zokrates compute-witness -a 7 13 91
+```
+
+A file named `witness` is generated.
+
+### 5. Creating a proof
+
+The following command produces a proof, using both the proving key and the witness:
+
+```sh
+zokrates generate-proof
+```
+
+The resulting file `proof.json` looks like the following:
+
+```json
+{
+  "scheme": "g16",
+  "curve": "bn128",
+  "proof": {
+    "a": [
+      "0x0a7ea3ca37865347396645d017c7623431d13103e9107c937d722e5da15f352b",
+      "0x040c202ba8fa153f84af8dabc2ca40ff534f54efeb3271acc04a70c41afd079b"
+    ],
+    "b": [
+      [
+        "0x0ec1e4faea792762de35dcfd0da0e6859ce491cafad455c334d2c72cb8b24550",
+        "0x0985ef1d036b41d44376c1d42ff803b7cab9f9d4cf5bd75298e0fab2d109f096"
+      ],
+      [
+        "0x265151afd8626b4c72dfefb86bac2b63489423d6cf895ed9fa186548b0b9e3f3",
+        "0x301f2b356621408e037649d0f5b4ad5f4b2333f58453791cc24f07d5673349bf"
+      ]
+    ],
+    "c": [
+      "0x2b75a257d68763100ca11afb3beae511732c1cd1d3f1ce1804cbc0c26043cb6b",
+      "0x2f80c706b58482eec9e759fce805585595a76c27e37b67af3463414246fbabbd"
+    ]
+  },
+  "inputs": [
+    "0x000000000000000000000000000000000000000000000000000000000000005b"
+  ]
+}
+```
+
+### 6. Export an sCrypt verifier
+
+Using our version of ZoKrates, we can export a project template, which will contain a verifier for our circuit. Simply run the following command:
+
+```sh
+zokrates export-verifier-scrypt
+``` 
+
+This will create a directory named `verifier`, containing the project. Let's set it up. Run the following:
+
+```sh
+cd verifier && git init && npm i
+```
+
+Now the verifier is ready to be used. In the following section we will go over the code and show how to use it.
+
+
+### 7. Run the sCrypt Verifier
+
+In the generated project, let's open the file `src/contracts/verifier.ts`. This file contains an sCrypt smart contract, named `Verifier`, which can be unlocked by providing a valid ZK proof.
+
+Under the hood it uses the `SNARK` library from `src/contracts/snark.ts`. This file includes an elliptic curve implementation along with a library that implements pairings over that elliptic curve and lastly the implementation of the proof verification algorithm. In our example the [`BN-256` elliptic curve](https://hackmd.io/@jpw/bn254) is being used along with the [`Groth-16` proof system](https://eprint.iacr.org/2016/260.pdf)..
+
+Let's take a look at the implementation of `Verifier`:
+
+```ts
+export class Verifier extends SmartContract {
+    
+    @prop()
+    vk: VerifyingKey
+
+    @prop()
+    publicInputs: FixedArray<bigint, typeof N_PUB_INPUTS>,
+
+    constructor(
+      vk: VerifyingKey,
+      publicInputs: FixedArray<bigint, typeof N_PUB_INPUTS>,
+      ) {
+        super(...arguments)
+        this.vk = vk
+        this.publicInputs = publicInputs
+    }
+    
+    @method()
+    public verifyProof(
+        proof: Proof
+    ) {
+        assert(SNARK.verify(this.vk, this.publicInputs, proof))
+    }
+
+}
+```
+
+As we can see, the contract has two properties, namely the verification key and the value(s) of the public inputs to our ZK program. 
+
+The contract also has a public method named `verifyProof`. As the name implies it verifies a ZK proof and can be unlocked by a valid one. The proof is passed as a parameter. The method calls the proof verification function:
+
+```ts
+SNARK.verify(this.vk, this.publicInputs, proof)
+```
+
+The function takes as parameters the verification key, the public inputs and the proof. It's important to note that the proof is cryptographically tied to the verification key and thus must be a proof about the correct ZoKrates program (`factor.zok`).
+
+The generated project will also contain a deployment script `deploy.ts`. Let's take a look at the code:
+
+```ts
+async function main() {
+    await Verifier.compile()
+    
+    // TODO: Adjust the amount of satoshis locked in the smart contract:
+    const amount = 100
+
+    // TODO: Insert public input values here:
+    const publicInputs: FixedArray<bigint, typeof N_PUB_INPUTS> = [ 0n ]
+
+    let verifier = new Verifier(
+        prepareVerifyingKey(VERIFYING_KEY_DATA),
+        publicInputs
+    )
+
+    // Connect to a signer.
+    await verifier.connect(getDefaultSigner())
+
+    // Deploy:
+    const deployTx = await verifier.deploy(amount)
+    console.log('Verifier contract deployed: ', deployTx.id)
+}
+
+main()
+```
+
+We can observe that we need to adjust two things. First, we need to set the amount of satoshis we will lock into the deployed smart contract. The second thing is the public input value, i.e. the product of the secret factors. Let's set it to the value `91`:
+
+```ts
+const publicInputs: FixedArray<bigint, typeof N_PUB_INPUTS> = [ 91n ]
+```
+
+Note also, that ZoKrates already provided us with the values of the verification key, that we created during the setup phase.
+
+Now, we can build and deploy the contract. Simply run:
+
+```sh
+npm run deploy
+```
+
+The first time you run the command, it will ask you to fund a testnet address. You can fund it using [our faucet](https://scrypt.io/faucet/).
+
+After a successful run you should see something like the following:
+
+```
+Verifier contract deployed:  2396a4e52555cdc29795db281d17de423697bd5cbabbcb756cb14cea8e947235
+```
+
+The smart contract is now deployed and can be unlocked using a valid proof, that proves the knowledge of the factors for the integer `91`. You can see [the transaction](https://test.whatsonchain.com/tx/2396a4e52555cdc29795db281d17de423697bd5cbabbcb756cb14cea8e947235) using a block explorer.
+
+Let's call the deployed contract. Let's create a file named `call.ts` with the following content:
+
+```ts
+import { DefaultProvider } from 'scrypt-ts'
+import { parseProofFile } from './src/util'
+import { Verifier } from './src/contracts/verifier'
+import { Proof } from './src/contracts/snark'
+import { getDefaultSigner } from './tests/utils/helper'
+import { PathLike } from 'fs'
+
+export async function call(txId: string, proofPath: PathLike) {
+    await Verifier.compile()
+
+    // Fetch TX via provider and reconstruct contract instance
+    const provider = new DefaultProvider()
+    const tx = await provider.getTransaction(txId)
+    const verifier = Verifier.fromTx(tx, 0)
+    
+    // Connect signer
+    await verifier.connect(getDefaultSigner())
+
+    // Parse proof.json
+    const proof: Proof = parseProofFile(proofPath)
+
+    // Call verifyProof()
+    const { tx: callTx } = await verifier.methods.verifyProof(
+        proof
+    )
+    console.log('Verifier contract unlocked: ', callTx.id)
+}
+
+(async () => {
+  await call('2396a4e52555cdc29795db281d17de423697bd5cbabbcb756cb14cea8e947235', '../proof.json')
+})()
+```
+
+The function `call` will create the contract instance from the passed [TXID](https://wiki.bitcoinsv.io/index.php/TXID) and call its `verifyProof` method. The proof gets parsed from `proof.json`, which we already created in the section above.
+
+Let's unlock our contract by running the following command:
+```
+npx ts-node call.ts
+```
+
+If everything goes as expected, we have now unlocked the verifier smart contract. You'll see an output similar to the following:
+
+```
+Verifier contract unlocked:  30127e0c340878d3fb7c165e2d082267eef2c8df79b5cf750896ef565ca7651d
+```
+
+Take a look at it using [a block explorer](https://test.whatsonchain.com/tx/30127e0c340878d3fb7c165e2d082267eef2c8df79b5cf750896ef565ca7651d).
+
+## Conclusion
+
+Congratulations! You have successfully created a zk-SNARK and verified it on-chain!
+
+If you want to learn how you can integrate zk-SNARKS into a fully fledged Bitcoin web application, take a look at our free [course](https://academy.scrypt.io/en/courses/Build-a-zkSNARK-based-Battleship-Game-on-Bitcoin-64187ae0d1a6cb859d18d72a), which will teach you how to create a ZK Battleship game.
+Additionally, it teaches you to use [snarkjs/circom](https://github.com/sCrypt-Inc/snarkjs).
+
+To know more about ZKP, you can refer to [this awesome list](https://github.com/sCrypt-Inc/awesome-zero-knowledge-proofs).