From 5c82a5f60fd99a8747c101c61382542b0b970028 Mon Sep 17 00:00:00 2001 From: mr-zwets <53938059+mr-zwets@users.noreply.github.com> Date: Tue, 17 Dec 2024 10:29:00 +0100 Subject: [PATCH] Improve docs (#245) --- website/docs/guides/infrastructure.md | 51 ++++++++++++++++++++++ website/docs/guides/syntax-highlighting.md | 7 +-- website/docs/language/globals.md | 2 +- website/sidebars.js | 1 + 4 files changed, 57 insertions(+), 4 deletions(-) create mode 100644 website/docs/guides/infrastructure.md diff --git a/website/docs/guides/infrastructure.md b/website/docs/guides/infrastructure.md new file mode 100644 index 00000000..849a7190 --- /dev/null +++ b/website/docs/guides/infrastructure.md @@ -0,0 +1,51 @@ +--- +title: Contract Infrastructure +--- + +When creating a smart contract application on Bitcoin Cash you'll need to investigate whether you need surrounding contract infrastructure. +Below we'll discuss the 2 main types of contract infrastructure you might run into: the need to store contract details and the need for a transaction server. + +## Storing Contract Details + +Because of the `pay-to-scripthash` (`P2SH`) standard for smart contracts on BCH, the details of the script are hidden after creating a contract UTXO. This means you need to store the full contract script to ensure you can spend from your smart contract later. + +:::caution +It is the responsibility of smart contract services/apps to keep track of the contract details making up the `P2SH` contract, as user-wallets are currently not smart enough to do this automatically. +::: + +When users are allowed to provide their own `constructor` arguments when creating a BCH smart contract, each contract creation will have a unique smart contract address. Only the constructor arguments in the contract bytecode are variable, the rest of the bytecode for a contract is static. This static part is derived from the CashScript source file, so storing the contract source file or artifact both has the same effect. + +:::note +To construct the full contract script you need both the `constructor` arguments and static contract bytecode (either the contract source file or the `Artifact`) to be available. +::: + + +### Off-chain storage + +To store the contract details off-chain, you will need to run a database server which stores the specific constructor arguments for each contract, this will translate into their respective smart contract addresses. Additionally, you should ensure that the CashScript source file or the contract artifact (which contains the static bytecode) is also stored for future reference. + +### On-chain storage + +Different applications like Tapswap and Cauldron have also started posting the `constructor` arguments with a contract-identifier to an `OP_RETURN` output during the contract creation. This way the contract details are available on-chain in a decentralized and recoverable way. + +:::tip +To store contract details on-chain, start the `OP_RETURN` data with an easily recognizable identifier, this way you can find all your smart contract UTXOs by checking the transactions including that identifier in the `OP_RETURN`. +::: + +## Transaction server + +When your smart contracts depend on "automatic settlement" or any events where transactions are invoked without the user being involved, you will need a transaction server to create and broadcast those transactions. Smart contracts on BCH are never self-executing, someone is always needed to invoke functionality on a smart contract by creating a transaction. + +There are 2 main types of events which might need a transaction server to trigger a smart contract transaction, namely time-related events and oracle-related events. + +### Time-related events + +Time-related events are when your smart contract uses absolute or relative locktimes, which require a waiting period before certain transactions can happen. However, if you want those transactions to 'automatically' happen when this locktime is reached, then you will need to create a transaction server to monitor the blockheight on an ongoing basis. + +:::tip +Both the `Electrum` and `Chaingraph` indexers allow you to create websocket subscriptions to listen for blockheight updates. +::: + +### Oracle-related events + +Oracle-related events are when your smart contract uses an oracle to listen for outside information, where some transactions can only happen if the oracle publishes certain information. However, if you want those transactions to 'automatically' happen when the oracle triggers this condition, then you will need to create a transaction server to monitor the oracle for triggers on an ongoing basis. diff --git a/website/docs/guides/syntax-highlighting.md b/website/docs/guides/syntax-highlighting.md index 2c69a56f..1e3e0c75 100644 --- a/website/docs/guides/syntax-highlighting.md +++ b/website/docs/guides/syntax-highlighting.md @@ -36,13 +36,14 @@ au BufRead,BufNewFile *.cash setfiletype solidity This associates `.cash` files with Solidity, and enables syntax highlighting for your CashScript files. -## GitHub & GitLab -GitHub and GitLab have syntax highlighting for Solidity built in. To associate `.cash` files with Solidity highlighting, add a `.gitattributes` file to your repository with the following contents: +## GitHub +GitHub has highlighting for Solidity built in. To associate `.cash` files with Solidity highlighting, add a `.gitattributes` file to your repository with the following contents: ```python title=".gitattributes" *.cash linguist-language=Solidity # GitHub -*.cash gitlab-language=solidity # GitLab ``` +Unfortunately Gitlab does not have properly working Soldidity highlighting through the `gitattributes` for now... + ## Others If your editor is not mentioned above, the steps are likely very similar. Try to find a Solidity syntax highlighting plugin for your editor of choice and find a method to associate `.cash` files with this Solidity highlighting. diff --git a/website/docs/language/globals.md b/website/docs/language/globals.md index 8b40a77f..a5473ccf 100644 --- a/website/docs/language/globals.md +++ b/website/docs/language/globals.md @@ -255,7 +255,7 @@ The units `sats`, `finney`, `bits` and `bitcoin` can be used to denominate Bitco ```solidity require(1 sats == 1); require(1 finney == 10); -require(1 bit == 100); +require(1 bits == 100); require(1 bitcoin == 1e8); ``` diff --git a/website/sidebars.js b/website/sidebars.js index d7f98d05..08afe66e 100755 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -48,6 +48,7 @@ module.exports = { items: [ 'guides/syntax-highlighting', 'guides/covenants', + 'guides/infrastructure', 'guides/walletconnect', 'guides/debugging', 'guides/optimization'