diff --git a/src/pages/general/support/troubleshooting.mdx b/src/pages/general/support/troubleshooting.mdx index ff733057..66f33065 100644 --- a/src/pages/general/support/troubleshooting.mdx +++ b/src/pages/general/support/troubleshooting.mdx @@ -1,10 +1,16 @@ -import { Callout } from "nextra/components"; -import CopyableCode from "@/components/CopyableCode"; +--- +title: Troubleshooting Guide +description: Solutions to common issues users and developers encounter on the Ink network. +--- + +import { Callout } from 'nextra/components' # Troubleshooting Guide This guide covers common issues developers and users might encounter when working with Ink, along with their solutions. +--- + ## Transaction Issues ### Nonce Out of Sync @@ -14,21 +20,18 @@ If you encounter JSON-RPC internal errors or transactions getting stuck, your wa #### For MetaMask Users: 1. Enable custom nonce in MetaMask: - - Go to Settings > Advanced - Enable "Customize transaction nonce" 2. Find your next valid nonce using either method A or B: **Method A: Using Block Explorer** - - - Go to (replace YOUR_ADDRESS with your address) + - Go to `https://explorer.inkonchain.com/address/YOUR_ADDRESS` (replace YOUR_ADDRESS with your address) - Find your most recent transaction where you were the sender (FROM address) - Click the transaction and then "View details" - - Find the nonce value and add 1 to it - this is your next valid nonce + - Find the nonce value and add 1 to it — this is your next valid nonce **Method B: Using Command Line** - ```bash curl -s -X POST -H "Content-Type: application/json" --data '{ "jsonrpc":"2.0", @@ -37,25 +40,148 @@ If you encounter JSON-RPC internal errors or transactions getting stuck, your wa "id":1 }' https://rpc-gel.inkonchain.com | python3 -c "import sys, json; print(int(json.load(sys.stdin)['result'], 16))" ``` - Replace `YOUR_ADDRESS` with your wallet address. The number returned is your next valid nonce. 3. Send a recovery transaction: - - Send a 0 ETH transaction to yourself - When prompted for the nonce, use the exact number you got from either method above - Increase the gas price slightly (tap + once in the Network Fee section) - The transaction should go through -4. Future transactions should now use the correct nonce +4. Future transactions should now use the correct nonce. + +The recovery transaction typically costs around $0.05 in gas fees. + +--- + +### Transaction Failed + +Failed transactions are usually caused by one of the following: + +**Insufficient gas** +Increase your gas limit before confirming. In MetaMask, click "Edit" on the gas estimate screen and set a higher limit. Ink is an L2 with low fees, so small increases cost very little. + +**RPC connection issue** +Your wallet may be connected to a slow or misconfigured RPC endpoint. Switch to an official Ink RPC: + +| Network | RPC URL | Chain ID | +|---|---|---| +| Ink Mainnet | `https://rpc-gel.inkonchain.com` | `57073` | +| Ink Sepolia (Testnet) | `https://rpc-gel-sepolia.inkonchain.com` | `763373` | + +**Contract-level revert** +Some failures are caused by the smart contract itself — for example, slippage set too low on a DEX, or an expired signature. Check the transaction on the [Ink Explorer](https://explorer.inkonchain.com) to see the revert reason. + +--- + +### Sent ETH to the Wrong Network + + + Do not attempt recovery by sending more funds. Assess the situation below first. + + +Ink is EVM-compatible, meaning the same wallet address exists across Ethereum, Optimism, Base, and Ink. Whether you can recover funds depends on where you sent them. + +**Sent between Ethereum ↔ Ink:** +Use the [Ink Bridge](https://inkonchain.com/bridge) to move funds back. Your funds are safe — they just need to be bridged to the correct network. + +**Sent to another EVM network (e.g., Arbitrum, Base, Polygon):** +Your funds are likely still accessible. Add that network to your wallet, switch to it, and you should see your balance there. + +**Sent to a non-EVM network (e.g., Solana, Bitcoin):** +Recovery is generally not possible. Contact the receiving wallet's support team immediately — some have special recovery processes. + +--- + +## Testnet + +### Testnet Tokens Not Arriving + +Ink Sepolia faucets are rate-limited to prevent abuse. Try the following in order: + +1. **Official Ink faucet** — Visit [docs.inkonchain.com/tools/faucets](https://docs.inkonchain.com/tools/faucets) and follow the instructions there. +2. **Alchemy Sepolia faucet** — [sepoliafaucet.com](https://sepoliafaucet.com) (requires a free Alchemy account). +3. **Wait 24 hours** — Most faucets enforce a per-address cooldown. Your request was likely registered and will arrive after the cooldown expires. - The recovery transaction typically costs around $0.05 in gas fees. + Make sure your wallet is connected to **Ink Sepolia** (Chain ID: `763373`), not Ethereum Sepolia, before checking your balance. +--- + +## Node Issues + +### Node Out of Sync + +If your node is falling behind the chain tip, work through these steps: + +**1. Verify your containers are running** +```bash +docker compose ps +``` +All services should show `Up`. If any show `Exited`, restart them: +```bash +docker compose up -d +``` + +**2. Check your sync status** +```bash +local_block=$(curl -s -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["finalized", false],"id":1}' \ + | jq -r .result.number | sed 's/^0x//' | awk '{printf "%d\n", "0x" $0}') + +remote_block=$(curl -s -X POST https://rpc-gel.inkonchain.com \ + -H "Content-Type: application/json" \ + --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["finalized", false],"id":1}' \ + | jq -r .result.number | sed 's/^0x//' | awk '{printf "%d\n", "0x" $0}') + +echo "Local: $local_block | Remote: $remote_block" +``` +Your node is synced when both numbers match. + +**3. Check system resources** +Ensure you have adequate resources, especially for archive nodes: +- 500 GB+ free disk space (archive nodes grow over time) +- At least 8 GB RAM +- A stable, low-latency internet connection + +**4. Post-Ecotone upgrade stall** +If you see `walking back L1Block with curr=0x0000...:0 next=0x0000...:0` in your logs, wait a few minutes — this typically resolves on its own. + +For full node setup instructions, see the [node repository](https://github.com/inkonchain/node). + +--- + +## DeFi / Protocols + +### A Protocol Isn't Working on Ink + +Some DeFi protocols deploy separately on each chain. If a protocol's UI isn't behaving as expected: + +1. Confirm your wallet is connected to **Ink Mainnet** (Chain ID: `57073`). +2. Check whether the protocol has officially announced Ink support — not all protocols are live on Ink yet. +3. Visit the protocol's official documentation or Discord to confirm their Ink deployment status and contract addresses. + +--- + +## Docs & Links + +### Page Not Found + +The Ink documentation is actively maintained and pages may move between updates. If you hit a 404: + +1. Try navigating from the [docs homepage](https://docs.inkonchain.com) to find the content manually. +2. Use the search bar at the top of the page to look up the topic by keyword. +3. [Open a GitHub issue](https://github.com/inkonchain/docs/issues/new) with the broken URL so maintainers can add a redirect. + +--- + ## Getting Help -If you're still experiencing issues: +If you're still experiencing issues after following the steps above: -1. Check the [Network Status Page](https://status.inkonchain.com/) for any ongoing incidents -2. Submit a detailed bug report on our [GitHub](https://github.com/inkonchain/docs/issues) +1. Check the [Network Status Page](https://status.inkonchain.com/) for any ongoing incidents. +2. Search existing issues on [GitHub](https://github.com/inkonchain/docs/issues) — someone may have already reported it. +3. Submit a detailed bug report on [GitHub](https://github.com/inkonchain/docs/issues/new). +4. Reach out to the community on [Telegram](https://t.me/inkonchain).