Before interacting with smart contracts on the BCH network, the CashScript SDK needs to instantiate a
Contract object. This is done by providing the contract's information and constructor arguments. After this instantiation, the CashScript SDK can interact with BCH contracts.
A CashScript contract can be instantiated by providing an
Artifact object, a list of constructor arguments, and optionally a
Artifact object is the result of compiling a CashScript contract. See the Language Documentation for more information on Artifacts. Compilation can be done using the standalone
cashc CLI or programmatically with the
cashc NPM package (see CashScript Compiler).
NetworkProvider is used to manage network operations for the CashScript contract. By default, a mainnet
ElectrumNetworkProvider is used, but alternative network providers can be used. See the section on NetworkProvider below.
A contract's address can be retrieved through the
address member field.
The number of opcodes in the contract's bytecode can be retrieved through the
opcount member field. This is useful to ensure that the contract is not too big, since Bitcoin Cash smart contracts can contain a maximum of 201 opcodes.
The size of the contract's bytecode in bytes can be retrieved through the
bytesize member field. This is useful to ensure that the contract is not too big, since Bitcoin Cash smart contracts can be 520 bytes at most.
When writing covenant contracts, the de facto limit is actually closer to 360 bytes due to technical factors.
Returns the contract's redeem script encoded as a hex string.
Returns the total balance of the contract in satoshis. Both confirmed and unconfirmed balance is included in this figure.
Returns all UTXOs that can be spent by the contract. Both confirmed and unconfirmed UTXOs are included.
The main way to use smart contracts once they have been instantiated is through the functions defined in the CashScript source code. These functions can be found by their name under
functions member field of a contract object. To call these functions, the parameters need to match ones defined in the CashScript code.
These contract functions return an incomplete
Transaction object, which needs to be completed by providing outputs of the transaction. More information about sending transactions is found on the Sending Transactions page.
You may notice the
SignatureTemplate object in the example above. When a contract function has a
sig parameter, it requires a cryptographic signature over the spending transaction. But to generate this signature, the transaction needs to be built first, which is not yet the case when a contract function is first called.
So in the place of a signature, a
SignatureTemplate can be passed, which will automatically generate the correct signature using the
signer parameter. This signer can be any representation of a private key, including BITBOX/BCHJS'
PrivateKey, WIF strings, or raw private key buffers. This ensures that any BCH library can be used.
When calling a covenant function, the first
SignatureTemplate parameter is used to generate the required sighash preimage. This is generally fine, but you should take extra care when using non-default hashtypes.
The CashScript SDK needs to connect to the BCH network to perform certain operations, like retrieving the contract's balance, or sending transactions. All network functionality that the CashScript SDK needs is encapsulated in a network provider. This allows different network providers to be used and makes it easy to swap out dependencies.
The ElectrumNetworkProvider uses electrum-cash to connect to the BCH network. This is the recommended provider for most use cases and is used as the default when no other provider is provided. Both
electrum parameters are optional, and they default to mainnet and a 2-of-3 ElectrumCluster with a number of reliable electrum servers.
The FullStackNetworkProvider uses FullStack.cash' infrastructure to connect to the BCH network. FullStack.cash' offers dedicated infrastructure and support plans for larger projects. Both
bchjs parameters are mandatory, where
bchjs is an instance of FullStack.cash' BCHJS.
The BitboxNetworkProvider uses Bitcoin.com's BITBOX to connect to the BCH network. Because BITBOX is no longer officially maintained it is not recommended to use this network provider, and it is only available for compatibility with older projects. Both
bitbox parameters are mandatory, where
bitbox is a BITBOX instance.
The BitcoinRpcNetworkProvider uses a direct connection to a BCH node. Note that a regular node does not have indexing, so any address of interest (e.g. the contract address) need to be registered by the node before sending any funds to those addresses. Because of this it is recommended to use a different network provider unless you have a specific reason to use the RPC provider.
A big strength of the NetworkProvider setup is that it allows you to implement custom providers. So if new BCH libraries are created in the future, it is simple to use them with CashScript. This also potentially enables the CashScript SDK to be used with other (partially) compatible networks, such as BTC or BSV.
cashc package. This package needs to be installed separately and exports two compilation functions.
Compiles a CashScript contract from a source file. This is the recommended compile method if you're using Node.js and you have a source file available.
Compiles a CashScript contract from a source code string. This is the recommended compile method if you're building a webapp, because
compileFile() only works from a Node.js context. This is also the recommended method if no source file is locally available (e.g. the source code is retrieved with a REST API).