Update Contract Deployment guide + sidebar order

Author: rkalis

website/docs/guides/deployment.md

@@ -7,17 +7,17 @@ sidebar_label: Contract Deployment
 
 In the UTXO model, multiple UTXOs can live on the same address and are spendable under the same conditions. Many contracts, like multisig wallets, vaults, or escrows, work exactly this way. You compile the contract, share the address, and anyone can send funds to it. There is no "deployment" step: the contract is ready to use the moment you know its address.
 
-Deployment becomes necessary when you're building **stateful contract systems with authentication**. In these systems, a unique CashToken category (token ID) identifies the contract and its state. The token ID is created through a special genesis transaction, and the contract UTXOs are initialized with the right tokens, capabilities, and state. This is what we mean by "deploying" a contract.
+Deployment becomes necessary when you're building **stateful contract systems**. In these systems, a unique CashToken category (token ID) identifies the contract and its state. The token ID is created through a special genesis transaction, and the contract UTXOs are initialized with the right tokens, capabilities, and state. This is what we mean by "deploying" a contract.
 
 :::tip
-If your contract simply enforces spending conditions (like requiring multiple signatures or a timelock), you don't need a deployment. Just use the contract address. Deployment is for systems where CashTokens authenticate and track contract state.
+If your contract simply enforces spending conditions, you don't need a deployment. Just use the contract address. Deployment is for systems where CashTokens authenticate and track contract state.
 :::
 
 ## Before the Genesis Transaction
 
 ### Contract Addresses
 
-CashScript contract addresses are **deterministic**: they are derived from the contract's compiled bytecode (the artifact) combined with the constructor arguments. Given the same artifact and the same arguments, you will always get the same address.
+CashScript contract addresses are **deterministic**: they are derived from the contract's compiled bytecode combined with the constructor arguments. Given the same artifact and the same arguments, you will always get the same address.
 
 ```ts
 import { Contract } from 'cashscript';
@@ -33,9 +33,9 @@ This means you can reconstruct a contract's address at any time, on any machine,
 
 ### Preparing Constructor Arguments
 
-Some constructor arguments are straightforward constants (block heights, timelocks). Others require preparation before deployment:
+Some constructor arguments are straightforward constants, others require preparation before deployment:
 
-- **Token IDs from other categories** — in complex systems with multiple token categories, contracts often reference each other's token IDs as constructor arguments. Note that token IDs must be byte-reversed when passed as constructor arguments, because the Bitcoin Cash VM uses little-endian byte order internally while token IDs are displayed in big-endian (the same applies to transaction IDs).
+- **Token IDs from other categories** — in complex systems with multiple token categories, contracts often reference each other's token IDs as constructor arguments.
 - **Locking bytecodes from other contracts** — in multi-contract systems, one contract may reference another by locking bytecode. This creates a dependency chain: you must instantiate the referenced contract first, extract its locking bytecode, and pass it as a constructor argument to the dependent contract.
 - **Public keys** — for contracts that validate signed messages (e.g. from an oracle provider), you need the signer's public key. For owner authentication, you need to derive the public key hash from a keypair ahead of time.
 
@@ -48,36 +48,25 @@ function reverseHex(hex: string): string {
 }
 
 // Token IDs must be byte-reversed for use as constructor args
-const argsA = [reverseHex(tokenIdB), reverseHex(tokenIdC)] as const;
+const argsA = [reverseHex(tokenIdX), reverseHex(tokenIdY)] as const;
 const contractA = new Contract(artifactA, [...argsA], { provider });
 
 // Extract locking bytecode to pass to a dependent contract
-const lockingBytecodeResult = cashAddressToLockingBytecode(contractA.address);
-if (typeof lockingBytecodeResult === 'string') throw new Error('Invalid address');
-const lockingBytecodeA = binToHex(lockingBytecodeResult.bytecode);
-
-const argsB = [lockingBytecodeA, oraclePublicKey, startBlockHeight] as const;
+const argsB = [contractA.lockingBytecode, oraclePublicKey, startBlockHeight] as const;
 const contractB = new Contract(artifactB, [...argsB], { provider });
 ```
 
 :::caution
-Constructor arguments are baked into the contract address. If any argument changes, even a single byte of a public key, the contract address changes entirely. Double-check all arguments before deploying. Some parameters, like fee destination addresses, are permanent once deployed and cannot be changed. The wallets behind these addresses require proper creation, backup, and security before deployment.
+Double-check all arguments before deploying. Some parameters, like fee destination addresses, are permanent once deployed and cannot be changed. The wallets behind these addresses require proper creation, backup, and security before deployment.
 :::
 
 ### Token IDs
 
-In Bitcoin Cash, a new token category is created when a UTXO with `vout: 0` is spent as input index 0 of a transaction. Both conditions must be met. The resulting token ID equals the txid of that spent UTXO.
-
-```ts
-// The token ID equals the txid of the vout0 UTXO spent as input index 0
-const tokenId = genesisUtxo.txid;
-```
-
-Once you have the vout0 UTXO, its txid (the future token ID) is already known before constructing the genesis transaction.
+In Bitcoin Cash, a new token category can be created by spending a UTXO with `vout: 0`. The resulting token ID equals the txid of the UTXO with `vout: 0`. So if you already know which UTXO you will use for the genesis transaction, you already know what the token ID will be and can use it directly.
 
 ### Setup Wallet
 
-To create vout0 UTXOs and broadcast the genesis transaction, you need a funded wallet. This is typically a standard P2PKH wallet derived from a WIF private key or an HD seed phrase, with enough BCH to fund all contract outputs (each needs at least dust amount, typically 1000 sats).
+To create vout0 UTXOs and broadcast the genesis transaction, you need a funded wallet. This is typically a standard P2PKH wallet derived with enough BCH to fund all contract outputs (each needs at least dust amount, typically 1000 sats).
 
 The setup wallet may already have UTXOs at vout 0, but usually you need to prepare them. You can do this by sending BCH from the setup wallet back to itself as the sole output of a transaction. Since it's the only output, it will be at index 0.
 
@@ -108,10 +97,6 @@ async function createVout0(
 
 For deployments with multiple token categories, you need multiple vout0 UTXOs, one per token category you want to create. Since contracts may reference each other's token IDs as constructor arguments, it is recommended to prepare all vout0 UTXOs first so that every token ID is known before instantiating any contracts. The genesis transactions themselves can then be broadcast in parallel since they have no inter-transaction dependencies.
 
-:::note
-If you plan to include a BCMR OP_RETURN in your genesis transaction, keep the setup wallet "quiet" with minimal transaction history. Some wallets resolve token metadata by querying all transactions on the vout0 address, and a busy address can cause this resolution to be slow or fail.
-:::
-
 :::tip
 Always test your full deployment flow on chipnet before mainnet. Validating your transaction structure, constructor arguments, and initial state encoding on chipnet first avoids costly mistakes.
 :::
@@ -138,13 +123,16 @@ const tokenId = genesisUtxo.txid;
 const txBuilder = new TransactionBuilder({ provider });
 txBuilder.addInput(genesisUtxo, template.unlockP2PKH());
 txBuilder.addOutput({
-  to: contractA.tokenAddress, amount: 1000n,
+  to: contractA.tokenAddress,
+  amount: 1000n,
   token: { category: tokenId, amount: 9223372036854775807n },
 });
 txBuilder.addOutput({
-  to: contractB.tokenAddress, amount: 1000n,
+  to: contractB.tokenAddress,
+  amount: 1000n,
   token: {
-    category: tokenId, amount: 0n,
+    category: tokenId,
+    amount: 0n,
     nft: { capability: 'minting', commitment: initialStateHex },
   },
 });
@@ -161,29 +149,20 @@ NFT commitments are used to encode the initial state of a contract at deployment
 Use `@bitauth/libauth` to encode values into commitment bytes. This ensures values follow the same VM number encoding that the Bitcoin Cash VM uses:
 
 ```ts
-import { binToHex, bigIntToVmNumber, padMinimallyEncodedVmNumber } from '@bitauth/libauth';
-
-// Encode a bigint as a fixed-length VM number (matching OP_NUM2BIN behaviour)
-function bigIntToFixedBytes(value: bigint, byteLength: number): string {
-  const minimal = bigIntToVmNumber(value);
-  if (minimal.length > byteLength) throw new Error('value exceeds the requested byteLength');
-  // Return early if already the right length — padMinimallyEncodedVmNumber
-  // would overshoot by one byte in this case
-  if (minimal.length === byteLength) return binToHex(minimal);
-  return binToHex(padMinimallyEncodedVmNumber(minimal, byteLength));
-}
+import { binToHex } from '@bitauth/libauth';
+import { encodeIntAsFixedBytes } from '@cashscript/utils';
 
 // Encode initial state as a commitment (e.g. 4-byte counter + 4-byte blockHeight)
 function encodeInitialState(counter: bigint, blockHeight: bigint): string {
-  return bigIntToFixedBytes(counter, 4) + bigIntToFixedBytes(blockHeight, 4);
+  const encodedCounter = encodeIntAsFixedBytes(counter, 4);
+  const encodedBlockHeight = encodeIntAsFixedBytes(blockHeight, 4);
+  return binToHex(encodedCounter) + binToHex(encodedBlockHeight);
 }
 ```
 
 ### UTXO Duplication
 
-For systems expecting concurrent usage, you can create multiple identical contract UTXOs in the same genesis transaction. Each duplicate UTXO sits on the same contract address with the same token type, allowing independent transactions to spend different UTXOs without conflicting. The number of duplicates you create determines the system's concurrency capacity. See [accidental race-conditions](/docs/guides/lifecycle#accidental-race-conditions) in the lifecycle guide for more on why this matters.
-
-When duplicating contract UTXOs that hold fungible tokens, the total supply should be evenly distributed across them. The last UTXO can absorb the remainder to ensure the total is exact:
+For systems expecting [concurrent usage](/docs/guides/concurrency), you can create multiple identical contract UTXOs in the same genesis transaction. Each duplicate UTXO sits on the same contract address with the same token type, allowing independent transactions to spend different UTXOs without conflicting. When duplicating contract UTXOs that hold fungible tokens, the total supply should be evenly distributed across them. The last UTXO can absorb the remainder to ensure the total is exact:
 
 ```ts
 const supplyPerUtxo = MAX_TOKEN_SUPPLY / BigInt(numberOfDuplicates);
@@ -195,7 +174,7 @@ const supplyLastUtxo = supplyPerUtxo + remainder;
 
 The [Bitcoin Cash Metadata Registry (BCMR)](https://cashtokens.org/docs/bcmr/chip/) is the standard for associating metadata (name, ticker, decimals, icon) with CashToken categories. The metadata is resolved through an authchain, a chain of transactions starting from a specific output in the genesis transaction.
 
-To set up the authchain during deployment, include a dust output (e.g. 1000 sats) to a designated authchain address as part of the genesis transaction. This output becomes the starting point for metadata resolution. Wallets and indexers follow the authchain from this output to find the latest BCMR metadata.
+To set up the authchain during deployment, include a dust output (e.g. 1000 sats) at output index 0 to a designated authchain address as part of the genesis transaction. This output becomes the starting point for metadata resolution. Wallets and indexers follow the authchain from this output to find the latest BCMR metadata.
 
 ```ts
 // Include a dust output for the BCMR authchain

website/sidebars.ts

@@ -61,10 +61,10 @@ const sidebars: SidebarsConfig = {
       items: [
         'guides/covenants',
         'guides/lifecycle',
-        'guides/concurrency',
         'guides/cashtokens',
         'guides/deployment',
         'guides/infrastructure',
+        'guides/concurrency',
         'guides/walletconnect',
         'guides/debugging',
         'guides/optimization',