===========================================
POP CALL CONTRACT
===========================================

Call a contract

Usage: pop call contract [OPTIONS] [PATH]

Arguments:
  [PATH]  Directory path without flag for your project [default: current directory]

Options:
  -p, --path <PATH>          Path to the contract build directory or a contract artifact
  -c, --contract <CONTRACT>  The address of the contract to call [env: CONTRACT=]
  -m, --message <MESSAGE>    The name of the contract message to call
  -a, --args [<ARGS>...]     The message arguments, encoded as strings
  -v, --value <VALUE>        The value to be transferred as part of the call [default: 0]
  -g, --gas <gas>            Maximum amount of gas to be used for this command. If not specified
                             it will perform a dry-run to estimate the gas consumed for the call
  -P, --proof-size <PROOF_SIZE>  Maximum proof size for this command. If not specified it will
                                 perform a dry-run to estimate the proof size required
  -u, --url <URL>            Websocket endpoint of a node
  -s, --suri <SURI>          Secret key URI for the account calling the contract
                             e.g. - for a dev account "//Alice"
                                  - with a password "//Alice///SECRET_PASSWORD"
  -w, --use-wallet           Use a browser extension wallet to sign the extrinsic
  -x, --execute              Submit an extrinsic for on-chain execution
  -D, --dry-run              Perform a dry-run via RPC to estimate the gas usage. This does not
                             submit a transaction
  -d, --dev                  Enables developer mode, bypassing certain user prompts for faster
                             testing. Recommended for testing and local development only
  -h, --help                 Print help

===========================================
USAGE
===========================================

# Interactive mode (recommended)
pop call contract

# Read-only query (no -x flag)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message get \
  --use-wallet

# State-changing call (with -x flag)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message transfer \
  --args 0x123... 1000 \
  --use-wallet \
  -x

# Dry run (estimate gas)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message flip \
  --use-wallet \
  --dry-run

===========================================
WHAT IT DOES
===========================================

Read-Only Queries (without -x):
- Query contract state
- No gas cost (free)
- Instant results
- No transaction submitted
- No state changes

State-Changing Calls (with -x):
- Modify contract state
- Costs gas
- Requires transaction signing
- Changes persisted on-chain
- Transaction included in block

Dry-Run (with --dry-run):
- Simulate call without submitting
- Estimate gas consumption
- Validate arguments
- No cost, no state changes

===========================================
KEY FLAGS EXPLAINED
===========================================

--contract <ADDRESS>:
- Contract address to call
- Can be set via CONTRACT env var
- Example: 5CLPm1CeUvJhZ8GCDZCR7nWZ2m3XXe4X5MtAQK69zEjut36A

--message <NAME>:
- Message (function) name to call
- Must match exactly as in contract
- Examples: "get", "transfer", "flip", "balance_of"

--args [<ARGS>...]:
- Message arguments as strings
- Space-separated
- Auto-encoded based on contract metadata
- Examples:
  - Address: 5GrwvaEF...
  - Number: 1000
  - Boolean: true, false
  - String: "MyToken"

--value <VALUE>:
- Amount to transfer with call (in plancks)
- Default: 0
- Use for payable messages
- Example: 1000000000000 (1 token with 12 decimals)

--gas <GAS>:
- Max gas limit for call
- Auto-estimated if not specified
- Increase if call fails with OutOfGas
- Example: 100000000000

--proof-size <SIZE>:
- Max proof size for call
- Auto-estimated if not specified
- Substrate storage proof limit
- Example: 1000000

--url <URL>:
- Chain endpoint to call
- Default: ws://localhost:9944
- Examples:
  - Local: ws://localhost:9944
  - PassetHub Testnet: wss://testnet-passet-hub.polkadot.io

--suri <SURI>:
- Secret URI for signing account
- For local dev only!
- Examples: //Alice, //Bob
- NEVER use on testnet/mainnet

--use-wallet:
- Use browser extension wallet
- ALWAYS use for testnet/mainnet
- More secure than --suri
- Prompts for signature

--execute (-x):
- Submit transaction on-chain
- **CRITICAL FLAG**
- Without: Read-only query (free)
- With: State-changing call (costs gas)

--dry-run (-D):
- Simulate call via RPC
- Estimate gas and validate args
- No transaction submitted
- Use before --execute

--dev (-d):
- Developer mode
- Bypasses confirmations
- Faster testing workflow
- Use for local dev only

--path <PATH>:
- Path to contract project or .contract file
- Default: current directory
- Needs contract metadata (.json)

===========================================
READ-ONLY vs STATE-CHANGING
===========================================

Read-Only Query (NO -x flag):
```bash
pop call contract \
  --contract 0xABC... \
  --message balance_of \
  --args 0x123... \
  --use-wallet
```
- Free (no gas cost)
- Instant result
- No transaction
- View contract state

State-Changing Call (WITH -x flag):
```bash
pop call contract \
  --contract 0xABC... \
  --message transfer \
  --args 0x456... 1000 \
  --use-wallet \
  -x
```
- Costs gas
- Modifies state
- Transaction submitted
- Included in block

**Rule: Use -x only when modifying state!**

===========================================
EXAMPLES
===========================================

# Query balance (read-only)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message balance_of \
  --args 0x123... \
  --use-wallet

# Transfer tokens (state-changing)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message transfer \
  --args 0x456... 1000 \
  --use-wallet \
  -x

# Call on testnet
pop call contract \
  --path . \
  --url wss://testnet-passet-hub.polkadot.io \
  --contract 0xABC... \
  --message get \
  --use-wallet

# Estimate gas before executing
pop call contract \
  --path . \
  --contract 0xABC... \
  --message transfer \
  --args 0x456... 1000 \
  --dry-run \
  --suri //Alice

# Call with value transfer (payable message)
pop call contract \
  --path . \
  --contract 0xABC... \
  --message deposit \
  --value 1000000000000 \
  --use-wallet \
  -x

# Dev mode (fast testing)
pop call contract \
  --contract 0xABC... \
  --message flip \
  --suri //Alice \
  --dev \
  -x

# Use CONTRACT env var
export CONTRACT=0xABC...
pop call contract \
  --message get \
  --use-wallet

# Call with custom gas
pop call contract \
  --contract 0xABC... \
  --message complex_operation \
  --gas 200000000000 \
  --proof-size 2000000 \
  --use-wallet \
  -x

===========================================
WORKFLOW: TESTING CONTRACT
===========================================

1. Deploy contract:
pop up --constructor new --args false --suri //Alice
CONTRACT=5CLPm...

2. Query initial state (read-only):
pop call contract \
  --contract $CONTRACT \
  --message get \
  --suri //Alice

3. Dry-run state change:
pop call contract \
  --contract $CONTRACT \
  --message flip \
  --dry-run \
  --suri //Alice

4. Execute state change:
pop call contract \
  --contract $CONTRACT \
  --message flip \
  --suri //Alice \
  -x

5. Verify state changed:
pop call contract \
  --contract $CONTRACT \
  --message get \
  --suri //Alice

===========================================
WORKFLOW: ERC20 INTERACTION
===========================================

# Check balance (read-only)
pop call contract \
  --contract $TOKEN_ADDRESS \
  --message balance_of \
  --args $USER_ADDRESS \
  --use-wallet

# Check total supply (read-only)
pop call contract \
  --contract $TOKEN_ADDRESS \
  --message total_supply \
  --use-wallet

# Transfer tokens (state-changing)
pop call contract \
  --contract $TOKEN_ADDRESS \
  --message transfer \
  --args $RECIPIENT_ADDRESS 1000 \
  --use-wallet \
  -x

# Approve spender (state-changing)
pop call contract \
  --contract $TOKEN_ADDRESS \
  --message approve \
  --args $SPENDER_ADDRESS 5000 \
  --use-wallet \
  -x

# Check allowance (read-only)
pop call contract \
  --contract $TOKEN_ADDRESS \
  --message allowance \
  --args $OWNER_ADDRESS $SPENDER_ADDRESS \
  --use-wallet

===========================================
TROUBLESHOOTING
===========================================

Error: "contract not found":
Solution: Check contract address is correct
- Verify address on block explorer
- Ensure deployed on correct network

Error: "message not found":
Solution: Check message name spelling
- Must match exactly (case-sensitive)
- Check contract metadata
- Use tab completion in interactive mode

Error: "invalid arguments":
Solution: Check argument types and count
- Review message signature in contract
- Ensure correct number of arguments
- Check argument types match

Error: "OutOfGas":
Solution: Increase gas limit
pop call contract --contract 0xABC... --message flip --gas 200000000000 -x

Error: "insufficient balance":
Solution: Fund calling account
- Local: Use dev accounts (have balance)
- Testnet: Get tokens from faucet

Error: "transaction failed":
Solution: Check with --dry-run first
pop call contract --contract 0xABC... --message flip --dry-run

State didn't change:
Solution: Did you use -x flag?
- Without -x: Read-only query
- With -x: State-changing execution

Wallet doesn't prompt:
Solution:
- Install polkadot-js/Talisman/SubWallet extension
- Unlock wallet
- Allow popups in browser

===========================================
BEST PRACTICES
===========================================

1. Always dry-run before execute:
   pop call contract --message flip --dry-run
   pop call contract --message flip -x

2. Use --use-wallet for testnet/mainnet:
   - More secure than --suri
   - Never use dev accounts on production

3. Verify read-only calls first:
   - Check state before modifying
   - Validate arguments work

4. Use CONTRACT env var for repeated calls:
   export CONTRACT=0xABC...
   pop call contract --message get

5. Save contract metadata:
   - Keep .contract or .json file
   - Required for encoding/decoding

6. Test on local before testnet:
   - Catch bugs early
   - No cost for mistakes

===========================================
INTERACTIVE MODE
===========================================

For ease of use, run interactive mode:

```bash
pop call contract
```

Prompts for:
1. Contract address
2. Message to call
3. Arguments (if required)
4. Execute or query
5. Sign transaction

Interactive mode is recommended for:
- Exploring contract functions
- Testing during development
- Learning contract interface

===========================================
NEXT STEPS
===========================================

Common patterns:

# Check state → Modify → Verify
pop call contract --contract $C --message get
pop call contract --contract $C --message flip -x
pop call contract --contract $C --message get

# Dry-run → Execute
pop call contract --contract $C --message transfer --args $TO 100 --dry-run
pop call contract --contract $C --message transfer --args $TO 100 -x

# Local test → Testnet deploy
# (test locally with --suri //Alice)
# (deploy to testnet with --use-wallet)

See: up/contract.txt, test/contract.txt
