add CashTokens guide

Author: mr-zwets

website/docs/guides/cashtokens.md

@@ -0,0 +1,94 @@
+---
+title: CashTokens
+sidebar_label: CashTokens
+---
+
+CashTokens are native tokens on Bitcoin Cash, meaning that they are validated by each full node on the network and their transaction rules checked by each miner when constructing new blocks. CashTokens added fungible and non-fungible token primitives.
+CashTokens was first proposed in February of 2022 and actived on Bitcoin Cash mainchain in May of 2023.
+
+:::tip
+The specification for CashTokens is the ['CHIP-2022-02-CashTokens: Token Primitives for Bitcoin '](https://github.com/cashtokens/cashtokens) document.
+:::
+
+## CashTokens Utxo data
+
+To understand CashTokens it is helpful to start with the layout of the UTXO data. In the `networkProvider` data from the SDK, the `token` property contains the new CashTokens fields:
+
+```ts
+interface Utxo {
+  txid: string;
+  vout: number;
+  satoshis: bigint;
+  token?: TokenDetails;
+}
+
+interface TokenDetails {
+  amount: bigint;
+  category: string;
+  nft?: {
+    capability: 'none' | 'mutable' | 'minting';
+    commitment: string;
+  };
+}
+```
+
+Note that a UTXO can hold both an `amount` of fungible tokens as well as an `nft`, as long as both have the same `category` (also reffered to as "tokenId"). 
+
+## CashTokens introspection data
+While CashTokens might seem overwhelming at first, realize that in contracts you will only use it through the following introspection details
+
+- **`bytes tx.inputs[i].tokenCategory`** - `tokenCategory` + `tokenCapability` of a specific input.
+- **`bytes tx.inputs[i].nftCommitment`** - NFT commitment data of a specific input.
+- **`int tx.inputs[i].tokenAmount`** - Amount of fungible tokens of a specific input.
+
+and their equivalent for outputs:
+
+- **`bytes tx.outputs[i].tokenCategory`** - `tokenCategory` + `tokenCapability` of a specific output.
+- **`bytes tx.outputs[i].nftCommitment`** - NFT commitment data of a specific output
+- **`int tx.outputs[i].tokenAmount`** - Amount of fungible tokens of a specific output.
+
+## CashTokens Gotchas
+There are two important "gotchas" to be aware of when developing with CashTokens in smart contracts for the first time
+
+#### 1) tokenCategory contains the nft-capability
+```solidity
+bytes tx.inputs[i].tokenCategory
+```
+
+When accessing the `tokenCategory` through introspection the result returns `0x` when that specific item does not contain tokens. If the item does have tokens it returns the `bytes32 tokenCategory`. When the item contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
+
+#### 2) tokenCategory encoding
+
+The `tokenCategory` introspection variable returns the tokenCategory in the original unreversed order, this is unlike wallets and explorers which use the reversed byte-order. So be careful about the byte-order of `tokenCategory` when working with BCH smart contracts.
+
+```ts
+// when using a standard encoded tokenId, reverse the hex before using it in your contract
+const contract = new Contract(artifact, [reverseHex(tokenId)], { provider })
+```
+
+generally not recommended to do the byte-reversal in script 
+```solidity
+  // NOT THIS
+  require(tx.inputs[0].tokenCategory == providedTokenId.reverse());
+```
+
+#### 3) "invisibe" empty nfts
+Because the nft-capability has no separate introspection item, and nothing is appended to the `tokenCategory` in case of capability `none`, empty nfts can be "invisibe" when combined with fungible tokens.
+
+```solidity
+  // Input 0 has an empty nft (commitment 0x) with providedTokenId
+  // If there was no empty nft the tokenCategory would return 0x
+  require(tx.inputs[0].nftCommitment == 0x);
+  require(tx.inputs[0].tokenAmount == 0);
+  require(tx.inputs[0].tokenCategory == providedTokenId);
+```
+
+contrast this with the following scenario where there is also fungible tokens of the same category:
+
+```solidity
+  // Input 0 might or might not have an empty nft (commitment 0x) with providedTokenId
+  // Either way, the tokenCategory would return providedTokenId
+  require(tx.inputs[0].nftCommitment == 0x);
+  require(tx.inputs[0].tokenAmount == 10);
+  require(tx.inputs[0].tokenCategory == providedTokenId);
+```

website/docs/language/globals.md

@@ -131,7 +131,7 @@ Represents the `nSequence` number of a specific input. This value of the input's
 bytes tx.inputs[i].tokenCategory
 ```
 
-Represents the `tokenCategory` of a specific input. Returns 0 when that specific input contains no tokens. When the input contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
+Represents the `tokenCategory` of a specific input. Returns `0x` when that specific input contains no tokens. When the input contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
 
 :::caution
 The `tokenCategory` introspection variable returns the tokenCategory in the original unreversed order, this is unlike wallets and explorers which use the reversed byte-order. So be careful about the byte-order of `tokenCategory` when working with BCH smart contracts.
@@ -149,7 +149,7 @@ Represents the NFT commitment data of a specific input.
 int tx.inputs[i].tokenAmount
 ```
 
-Represents the amount of fungible tokens of a specific input.
+Represents the amount of fungible tokens of a specific input. Maximum size for a `tokenAmount` is a 64-bit integer.
 
 ### tx.outputs
 Represents the list of outputs of the evaluated transaction. This is an array, and cannot be used on itself. You need to access an output with a specific index and specify the properties you want to access.
@@ -180,7 +180,7 @@ Represents the locking bytecode (`scriptPubKey`) of a specific output.
 bytes tx.output[i].tokenCategory
 ```
 
-Represents the `tokenCategory` of a specific output. Returns 0 when that specific output contains no tokens. When the output contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
+Represents the `tokenCategory` of a specific output. Returns `0x` when that specific output contains no tokens. When the output contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
 
 :::caution
 The `tokenCategory` introspection variable returns the tokenCategory in the original unreversed order, this is unlike wallets and explorers which use the reversed byte-order. So be careful about the byte-order of `tokenCategory` when working with BCH smart contracts.
@@ -198,7 +198,7 @@ Represents the NFT commitment data of a specific output.
 int tx.output[i].tokenAmount
 ```
 
-Represents the amount of fungible tokens of a specific output.
+Represents the amount of fungible tokens of a specific output. Maximum size for a `tokenAmount` is a 64-bit integer.
 
 ## Constructing locking bytecode
 One of the main use cases of covenants is enforcing transaction outputs (where money is sent). To assist with enforcing these outputs, there is a number of `LockingBytecode` objects that can be instantiated. These locking bytecodes can then be compared to the locking bytecodes of transaction outputs.

…bsite/docs/guides/syntax-highlighting.md …ite/docs/language/syntax-highlighting.mdwebsite/docs/guides/syntax-highlighting.md renamed to website/docs/language/syntax-highlighting.md website/docs/guides/syntax-highlighting.md renamed to website/docs/language/syntax-highlighting.md

@@ -57,6 +57,15 @@ interface Utxo {
   satoshis: bigint;
   token?: TokenDetails;
 }
+
+interface TokenDetails {
+  amount: bigint;
+  category: string;
+  nft?: {
+    capability: 'none' | 'mutable' | 'minting';
+    commitment: string;
+  };
+}
 ```
 
 #### Example

website/docs/sdk/electrum-network-provider.md

@@ -35,6 +35,15 @@ interface Utxo {
   satoshis: bigint;
   token?: TokenDetails;
 }
+
+interface TokenDetails {
+  amount: bigint;
+  category: string;
+  nft?: {
+    capability: 'none' | 'mutable' | 'minting';
+    commitment: string;
+  };
+}
 ```
 
 #### Example

website/docs/sdk/network-provider.md

@@ -121,6 +121,7 @@ module.exports = {
           { from: '/docs/sdk', to: '/docs/sdk/instantiation' },
           { from: '/docs/sdk/transactions-advanced', to: '/docs/sdk/transaction-builder' },
           { from: '/docs/guides', to: '/docs/guides/covenants' },
+          { from: '/docs/guides/syntax-highlighting', to: '/docs/language/syntax-highlighting' },
           { from: '/docs/getting-started', to: '/docs/basics/getting-started' },
           { from: '/docs/examples', to: '/docs/language/examples' },
         ],

website/docusaurus.config.js

@@ -18,6 +18,7 @@ module.exports = {
         'language/functions',
         'language/globals',
         'language/examples',
+        'language/syntax-highlighting'
       ],
     },
     {
@@ -54,8 +55,8 @@ module.exports = {
       type: 'category',
       label: 'Guides',
       items: [
-        'guides/syntax-highlighting',
         'guides/covenants',
+        'guides/cashtokens',
         'guides/infrastructure',
         'guides/walletconnect',
         'guides/debugging',