Globally available units
An integer literal can take a suffix of either monetary or temporary units to add semantic value to these integers and to simplify arithmetic. When these units are used, the underlying integer is automatically multiplied by the value of the unit. The units
bitcoin are used to denote monetary value, while the units
weeks are used to denote time.
Be careful when using these units in precise calendar calculations though, because not every year equals 365 days and not even every minute has 60 seconds because of leap seconds.
Global time lock variables
Bitcoin Cash has support for different kinds of time locks, which can be used to specify time-based conditions inside Bitcoin Cash contracts. These time locks can be separated by three main attributes: location, targeting and metric. The location can be the transaction level or the contract level, but contract level locks also require you to use a corresponding transaction level lock. The targeting can be relative (e.g. at least 4 hours have passed) or absolute (e.g. the block number is at least 600,000). The metric can be blocks or seconds.
It can be difficult to fully grasp the intricacies of time locks, so if you're starting out it is recommended to start off with the simplest version: absolute block-based time locks. If you do want to dive into the more advanced uses of time locks, James Prestwich wrote the best article explaining time locks in Bitcoin that also fully applies to Bitcoin Cash.
tx.time is used to create absolute time locks. The value of
tx.time can either represent the block number of the spending transaction or its timestamp. When comparing it with values below
500,000,000, it is treated as a blocknumber, while higher values are treated as a timestamp.
Due to limitations in the underlying Bitcoin Script,
tx.time can only be used in the following way:
Because of the way time locks work, a corresponding time lock needs to be added to the transaction. The CashScript SDK automatically sets this transaction level time lock to the most recent block number, as this is the most common use case. If you need to use a different block number or timestamp, this should be passed into the CashScript SDK using the
withTime() function. If the default matches your use case, no additional actions are required.
tx.time corresponds to the
nLocktime field of the current transaction and the
tx.age is used to create relative time locks. The value of
tx.age can either represent a number of blocks, or a number of chunks, which are 512 seconds. The corresponding transaction level time lock determines which of the two options is used.
Due to limitations in the underlying Bitcoin Script,
tx.age can only be used in the following way:
Because of the way time locks work, a corresponding time lock needs to be added to the transaction. This can be done in the CashScript SDK using the
withAge() function. However, the value passed into this function will always be treated as a number of blocks, so it is currently not supported to use
tx.age as a number of second chunks.
tx.age corresponds to the
nSequence field of the current UTXO and the
Global covenant variables
To explore the possible uses of covenants inside smart contracts, read the CashScript Covenants Guide.
Because of the way covenants work in the underlying Bitcoin Script, the sighash preimage needs to be verified by the contract. This is done automatically by including a signature check statement anywhere in the code outside of if-statements. This statement is then used by the compiler to verify the preimage.
Represents the version of the current transaction. Different transaction versions can have differences in functionality. Currently only version 1 and 2 exist, where only version 2 has support for BIP68.
tx.version is of type
bytes4 so to use it as an integer it needs to be cast to
Represents the double sha256 of the serialisation of all input outpoints.
Represents the double sha256 of the serialisation of the
nSequence field of all inputs.
Represents the outpoint of the current input (
bytes32 txid concatenated with
Represents the Bitcoin Script bytecode of the current contract. This can be used to enforce sending money back to the contract in combination with
Represents the value of current UTXO being spent. This can be used to enforce the full balance or a specific part of the contract's balance to be spent.
tx.value is of type
bytes8 so its value could be too large to fit in an
int (max ~21 BCH). So you should make sure that the value is small enough before casting it to an integer. For safety, casting
int is disabled and you need to force cast it by casting to
nSequence field of the current input.
Represents the double SHA-256 hash of the serialisation of all outputs (
bytes8 amount +
bytes locking script). Can be used to enforce sending specific amounts to specific addresses.
nLocktime field of the current input.
Represents the hashtype used for the generation of the sighash and transaction signature. Can be used to enforce that the spender uses a specific hashtype. See the sighash docs for the implications of different hashtypes.
One of the main use cases of covenants is enforcing transaction outputs (where money is sent and how much). To assist with enforcing these outputs, there is a number of
Output objects that can be instantiated. These objects are then used in combination with
tx.hashOutputs as shown in the
Creates new P2PKH output serialisation for an output sending
Creates new P2SH output serialisation for an output sending
Creates new OP_RETURN output serialisation for an output containing an OP_RETURN script with
chunks as its data.