update smart contracts

Author: juanfranblanco

docs/smart-contracts/deploy-a-contract.md

@@ -25,9 +25,13 @@ After defining your contract's typed DTOs (as covered in [Contract Interaction](
 dotnet add package Nethereum.Web3
 ```
 
+You need a funded account to deploy — deployment is a transaction that costs gas.
+
 ## Using a Code-Generated Deployment Class
 
-The recommended approach is to use Nethereum's code generator to create typed deployment classes from your Solidity ABI and bytecode:
+The recommended approach is to use Nethereum's [code generator](./code-generation.md) to create typed deployment classes from your Solidity ABI and bytecode. The generated class inherits from `ContractDeploymentMessage` and contains the bytecode and constructor parameters as properties.
+
+Once you have the deployment class, create a `Web3` instance with your account, populate the constructor parameters, and send:
 
 ```csharp
 using Nethereum.Web3;
@@ -50,25 +54,37 @@ string contractAddress = transactionReceipt.ContractAddress;
 Console.WriteLine($"Contract deployed at: {contractAddress}");
 ```
 
+The handler encodes your constructor parameters into the deployment bytecode, estimates gas (unless you set it explicitly), manages the nonce, and waits for the transaction to be mined. The `ContractAddress` on the receipt is the address of your new contract.
+
 ## Estimating Deployment Gas
 
+If you want to check the gas cost before committing to the deployment, call `EstimateGasAsync` first. This simulates the deployment against the current chain state without actually sending a transaction:
+
 ```csharp
 var estimatedGas = await deploymentHandler.EstimateGasAsync(deploymentMessage);
 Console.WriteLine($"Estimated gas: {estimatedGas.Value}");
 deploymentMessage.Gas = estimatedGas;
 ```
 
+Note that `SendRequestAndWaitForReceiptAsync` estimates gas automatically if you don't set `Gas` on the message — so this step is only needed when you want to display the cost to a user or set a specific gas limit.
+
 ## Deploy Without Code-Generated Classes
 
+When prototyping or working with a raw ABI string, you can deploy without a typed class. Pass the ABI, bytecode, sender address, gas limit, and constructor arguments directly:
+
 ```csharp
 var receipt = await web3.Eth.DeployContract.SendRequestAndWaitForReceiptAsync(
     abi, bytecode, account.Address,
     new Nethereum.Hex.HexTypes.HexBigInteger(3000000),
     null, null, Web3.Convert.ToWei(1000000));
 ```
 
+This approach is less safe — constructor argument types aren't checked at compile time, so a mismatch will fail at runtime. Use the typed approach for production code.
+
 ## Deploying with Multiple Constructor Parameters
 
+Contracts often take multiple constructor arguments. Each parameter maps to a property on the deployment message class:
+
 ```csharp
 var deployment = new MyNFTDeployment
 {
@@ -81,8 +97,12 @@ var handler = web3.Eth.GetContractDeploymentHandler<MyNFTDeployment>();
 var receipt = await handler.SendRequestAndWaitForReceiptAsync(deployment);
 ```
 
+The `[Parameter]` attributes on the deployment class (defined in [Contract Interaction](./guide-smart-contract-interaction)) control how each property maps to the Solidity constructor signature.
+
 ## Checking Deployment Status
 
+The receipt's `Status` field tells you whether the deployment succeeded. A status of `1` means success; `0` means the transaction was mined but the contract creation reverted (often due to a `require` failing in the constructor):
+
 ```csharp
 if (receipt.Status.Value == 1)
 {

docs/smart-contracts/erc20.md

@@ -16,10 +16,12 @@ var receipt = await erc20.TransferRequestAndWaitForReceiptAsync(recipient, amoun
 No ABI, no code generation — built-in typed service for any ERC-20 token.
 :::
 
-Nethereum has built-in typed services for ERC-20 tokens. No ABI needed, no code generation — just call the methods directly. This is the fastest way to interact with any ERC-20 token and covers the vast majority of use cases.
+Nethereum has built-in typed services for ERC-20 tokens. No ABI needed, no code generation — just call the methods directly. This is the fastest way to interact with any ERC-20 token and covers the vast majority of use cases. For the full list of built-in services (ERC-721, ERC-1155, ENS, and more), see [Built-in Standards](./guide-built-in-standards.md).
 
 ## Query Token Info
 
+Every ERC-20 token exposes metadata — the name, symbol, decimals, and total supply. These are read-only calls (no gas, no signing needed):
+
 ```csharp
 var erc20 = web3.Eth.ERC20.GetContractService(contractAddress);
 
@@ -33,15 +35,21 @@ Console.WriteLine($"Decimals: {decimals}");
 Console.WriteLine($"Total supply: {Web3.Convert.FromWei(totalSupply, decimals)}");
 ```
 
+The `decimals` value is important — ERC-20 tokens store balances as integers in the smallest unit (like Wei for ETH). Most tokens use 18 decimals, but stablecoins like USDC use 6. Always use `Web3.Convert.FromWei(value, decimals)` to display human-readable amounts.
+
 ## Check Balance
 
+Balances are returned in the token's smallest unit. Use `FromWei` with the token's decimals to get a readable value:
+
 ```csharp
 var balance = await erc20.BalanceOfQueryAsync(myAddress);
 Console.WriteLine($"Balance: {Web3.Convert.FromWei(balance, decimals)} {symbol}");
 ```
 
 ## Transfer Tokens
 
+To transfer tokens, you need a `Web3` instance connected with a funded account (as shown in the [Contract Interaction guide](./guide-smart-contract-interaction.md)). The amount must be in the smallest unit — use `ToWei` with the token's decimals:
+
 ```csharp
 var receipt = await erc20.TransferRequestAndWaitForReceiptAsync(
     recipientAddress,
@@ -50,9 +58,11 @@ var receipt = await erc20.TransferRequestAndWaitForReceiptAsync(
 Console.WriteLine($"Transfer TX: {receipt.TransactionHash}");
 ```
 
+Gas estimation, nonce management, and EIP-1559 fees are handled automatically.
+
 ## Approve and TransferFrom
 
-The approve/transferFrom pattern allows another address (like a DEX) to spend your tokens:
+The approve/transferFrom pattern allows another address (like a DEX or smart contract) to spend your tokens. This is a two-step process: first you approve a spending limit, then the spender calls `transferFrom`.
 
 ```csharp
 // Approve the spender to use 1000 tokens
@@ -65,8 +75,12 @@ var allowance = await erc20.AllowanceQueryAsync(myAddress, spenderAddress);
 Console.WriteLine($"Allowance: {Web3.Convert.FromWei(allowance, decimals)}");
 ```
 
+Be careful with approvals — approving a large amount gives the spender permission to transfer up to that amount at any time. Many DApps request unlimited approval (`BigInteger.MaxValue`) for convenience, but it's safer to approve only what's needed.
+
 ## Listen for Transfer Events
 
+ERC-20 transfers emit a `Transfer` event. You can query historical transfers or monitor for new ones. Nethereum ships a built-in `TransferEventDTO` for ERC-20, so you don't need to define your own:
+
 ```csharp
 var transferEvent = web3.Eth.GetEvent<TransferEventDTO>(contractAddress);
 var filter = transferEvent.CreateFilterInput(
@@ -80,16 +94,20 @@ foreach (var t in transfers)
 }
 ```
 
+For more advanced filtering (by sender, recipient, block range), see the [Events guide](./guide-events.md).
+
 ## Historical Queries
 
-All query methods accept an optional `BlockParameter` for historical state:
+All query methods accept an optional `BlockParameter` to read state at a specific block. This is useful for checking what a balance was at a past point in time:
 
 ```csharp
 var historicalBalance = await erc20.BalanceOfQueryAsync(
     myAddress,
     new BlockParameter(15_000_000));
 ```
 
+The node must have archive state for this block — most public RPC providers only keep recent state. Use an archive node for deep historical queries.
+
 ## Next Steps
 
 - [Code Generation](./code-generation.md) -- generate typed services for custom contracts beyond ERC-20