plugin: forc-call

docs/book/spell-check-custom-words.txt

@@ -237,4 +237,8 @@ FuelLabs
 github
 toml
 hardcoded
-subdirectories
+subdirectories
+RawSlice
+StringArray
+StringSlice
+calldata

docs/book/src/SUMMARY.md

@@ -99,6 +99,7 @@
       - [forc deploy](./forc/plugins/forc_client/forc_deploy.md)
       - [forc run](./forc/plugins/forc_client/forc_run.md)
       - [forc submit](./forc/plugins/forc_client/forc_submit.md)
+      - [forc call](./forc/plugins/forc_client/forc_call.md)
     - [forc crypto](./forc/plugins/forc_crypto.md)
     - [forc debug](./forc/plugins/forc_debug.md)
     - [forc doc](./forc/plugins/forc_doc.md)

docs/book/src/forc/plugins/forc_client/forc_call.md

@@ -0,0 +1,307 @@
+# Forc Call
+
+`forc-call` is a command-line tool for interacting with deployed Fuel contracts. It allows you to make contract calls, query contract state, and interact with any deployed contract on the Fuel network - all from your command line!
+
+The `forc call` command is part of the Forc toolchain and is installed alongside other Forc tools.
+
+## Getting Started
+
+Here are a few examples of what you can do with `forc call`:
+
+Call a simple addition function on a deployed contract (in dry-run mode):
+
+```bash
+forc call 0xe18de7c7c8c61a1c706dccb3533caa00ba5c11b5230da4428582abf1b6831b4d \
+  --abi ./out/debug/counter-contract-abi.json \
+  add 1 2
+```
+
+Query the owner of a deployed DEX contract on testnet:
+
+```bash
+forc call \
+  --testnet \
+  --abi https://raw.githubusercontent.com/mira-amm/mira-v1-periphery/refs/heads/main/fixtures/mira-amm/mira_amm_contract-abi.json \
+  0xd5a716d967a9137222219657d7877bd8c79c64e1edb5de9f2901c98ebe74da80 \
+  owner
+```
+
+## Usage
+
+The basic syntax for `forc call` is:
+
+```bash
+forc call [OPTIONS] --abi <ABI-PATH/URL> <CONTRACT_ID> <SELECTOR> [ARGS]...
+```
+
+Where the following arguments are required:
+
+- `CONTRACT_ID` is the ID of the deployed contract you want to interact with
+- `ABI-PATH/URL` is the path or URL to the contract's JSON ABI file
+- `SELECTOR` is the function name (selector) you want to call
+- `ARGS` are the arguments to pass to the function
+
+## CLI Reference
+
+<details>
+  <summary><b>Forc Call CLI reference</b></summary>
+
+```sh
+forc call --help
+```
+
+```output
+Perform Fuel RPC calls from the comfort of your command line
+
+Usage: forc call [OPTIONS] --abi <ABI> <CONTRACT_ID> <FUNCTION> [FUNCTION_ARGS]...
+
+Arguments:
+  <CONTRACT_ID>
+    The contract ID to call
+
+  <FUNCTION>
+    The function signature to call. When ABI is provided, this should be a selector (e.g. "transfer") When no ABI is provided, this should be the full function signature (e.g. "transfer(address,u64)")
+
+  [FUNCTION_ARGS]...
+    Arguments to pass into the function to be called
+
+Options:
+  --abi <ABI>
+    Path or URI to a JSON ABI file
+
+  --node-url <NODE_URL>
+    The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's `network` table, then falls back to `http://127.0.0.1:4000`
+
+    You can also use `--target`, `--testnet`, or `--mainnet` to specify the Fuel node.
+
+    [env: FUEL_NODE_URL=]
+
+  --target <TARGET>
+    Preset configurations for using a specific target.
+
+    You can also use `--node-url`, `--testnet`, or `--mainnet` to specify the Fuel node.
+
+    Possible values are: [local, testnet, mainnet]
+
+  --mainnet
+    Use preset configuration for mainnet.
+
+    You can also use `--node-url`, `--target`, or `--testnet` to specify the Fuel node.
+
+  --testnet
+    Use preset configuration for testnet.
+
+    You can also use `--node-url`, `--target`, or `--mainnet` to specify the Fuel node.
+
+  --devnet
+    Use preset configuration for devnet.
+
+    You can also use `--node-url`, `--target`, or `--testnet` to specify the Fuel node.
+
+  --signing-key <SIGNING_KEY>
+    Derive an account from a secret key to make the call
+
+    [env: SIGNING_KEY=]
+
+  --wallet
+    Use forc-wallet to make the call
+
+  --amount <AMOUNT>
+    Amount of native assets to forward with the call
+
+    [default: 0]
+
+  --asset-id <ASSET_ID>
+    Asset ID to forward with the call
+
+  --gas-forwarded <GAS_FORWARDED>
+    Amount of gas to forward with the call
+
+  --mode <MODE>
+    The execution mode to use for the call; defaults to dry-run; possible values: dry-run, simulate, live
+
+    [default: dry-run]
+
+  --gas-price <PRICE>
+    Gas price for the transaction
+
+  --script-gas-limit <SCRIPT_GAS_LIMIT>
+    Gas limit for the transaction
+
+  --max-fee <MAX_FEE>
+    Max fee for the transaction
+
+  --tip <TIP>
+    The tip for the transaction
+
+  --external-contracts <EXTERNAL_CONTRACTS>
+    The external contract addresses to use for the call If none are provided, the call will automatically populate external contracts by making a dry-run calls to the node, and extract the contract addresses based on the revert reason
+
+  --output <OUTPUT>
+    The output format to use; possible values: default, raw
+
+    [default: default]
+
+  -h, --help
+    Print help (see a summary with '-h')
+
+  -V, --version
+    Print version
+```
+
+</details>
+
+## Type Encoding
+
+When passing arguments to contract functions, values are encoded according to their Sway types.
+Here's how to format different types:
+
+| Types                                         | Example input                                                        | Notes                                                                                          |
+|-----------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| bool                                          | `true` or `false`                                                    |                                                                                                |
+| u8, u16, u32, u64, u128, u256                 | `42`                                                                 |                                                                                                |
+| b256                                          | `0x0000000000000000000000000000000000000000000000000000000000000042` or `0000000000000000000000000000000000000000000000000000000000000042` | `0x` prefix is optional |
+| bytes, RawSlice                               | `0x42` or `42`                                                       | `0x` prefix is optional                                                                                               |
+| String, StringSlice, StringArray (Fixed-size) | `"abc"`                                                              |                                                                                                |
+| Tuple                                         | `(42, true)`                                                         | The types in tuple can be different                                                                                               |
+| Array (Fixed-size), Vector (Dynamic)          | `[42, 128]`                                                          | The types in array or vector must be the same; i.e. you cannot have `[42, true]`              |
+| Struct                                        | `{42, 128}`                                                          | Since structs are packed encoded, the attribute names are not encoded; i.e. `{42, 128}`; this could represent the following `struct Polygon { x: u64, y: u64 }` |
+| Enum                                          | `(Active: true)` or `(1: true)`       | Enums are key-val pairs with keys as being variant name (case-sensitive) or variant index (starting from 0) and values as being the variant value; this could represent the following `enum MyEnum { Inactive, Active(bool) }` |
+
+## ABI Support
+
+The ABI (Application Binary Interface) can be provided in two ways.
+
+### Local file
+
+```bash
+forc call <CONTRACT_ID> --abi ./path/to/abi.json <FUNCTION> [ARGS...]
+```
+
+### Remote ABI file/URL
+
+```bash
+forc call <CONTRACT_ID> --abi https://example.com/abi.json <FUNCTION> [ARGS...]
+```
+
+## Network Configuration
+
+```bash
+forc call --node-url http://127.0.0.1:4000 ...
+# or
+forc call --target local ...
+```
+
+## Advanced Usage
+
+### Using Wallets
+
+```sh
+# utilising the forc-wallet
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --wallet
+```
+
+```sh
+# with an explicit signing key
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --signing-key <KEY>
+```
+
+### Asset Transfers
+
+```sh
+# Native asset transfer
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --amount 100 --live
+```
+
+```sh
+# Custom asset transfer
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> \
+    --amount 100 \
+    --asset-id 0x1234... \
+    --live
+```
+
+### Gas Configuration
+
+```sh
+# Set gas price
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --gas-price 1
+
+# Forward gas to contract
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --gas-forwarded 1000
+
+# Set maximum fee
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --max-fee 5000
+```
+
+### Common Use Cases
+
+- 1. Contract State Queries
+
+```sh
+# Read contract state
+forc call <CONTRACT_ID> --abi <PATH> get_balance
+
+# Query with parameters
+forc call <CONTRACT_ID> --abi <PATH> get_user_info 0x1234...
+```
+
+- 2. Token Operations
+
+```sh
+# Check token balance
+forc call <CONTRACT_ID> --abi <PATH> balance_of 0x1234...
+
+# Transfer tokens
+forc call <CONTRACT_ID> --abi <PATH> transfer 0x1234... 100 --live
+```
+
+- 3. Contract Administration
+
+```sh
+# Check contract owner
+forc call <CONTRACT_ID> --abi <PATH> owner
+
+# Update contract parameters
+forc call <CONTRACT_ID> --abi <PATH> update_params 42 --live
+```
+
+## Tips and Tricks
+
+- Use `--mode simulate` to estimate gas costs before making live transactions
+- External contracts are automatically detected (via internal simulations), but can be manually specified with `--external-contracts`
+- For complex parameter types (tuples, structs, enums), refer to the parameter types table above
+- Always verify contract addresses and ABIs before making live calls
+- Use environment variables for sensitive data like signing keys: `SIGNING_KEY=<key>`
+
+## Troubleshooting
+
+### Common issues and solutions
+
+- **ABI Mismatch**:
+  - Ensure the ABI matches the deployed contract
+  - Verify function selectors match exactly
+
+- **Parameter Type Errors**:
+  - Check parameter formats in the types table
+  - Ensure correct number of parameters
+
+- **Network Issues**:
+  - Verify node connection
+  - Check network selection (testnet/mainnet)
+
+- **Transaction Failures**:
+  - Use simulation mode to debug
+  - Check gas settings
+  - Verify wallet has sufficient balance
+
+## Future Features
+
+The following features are planned for future releases:
+
+- Decode and display logs for contract calls
+- Support direct transfer of asset(s) to addresses
+- Function signature based calls without ABI
+- Raw calldata input support
+- Function selector completion
+- Enhanced error messages, debugging, and logging (additional verbosity modes)