From 60c2bcd6d2187824dc7fc1a875b706d6fca8f361 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 12:05:34 -1000 Subject: [PATCH 1/9] docs(skill): guide testnet and mainnet funding --- skills/foc-cli/SKILL.md | 2 +- skills/foc-cli/references/mainnet-funding.md | 15 ++++++- skills/foc-cli/references/testnet-funding.md | 45 ++++++++++++++++++++ 3 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 skills/foc-cli/references/testnet-funding.md diff --git a/skills/foc-cli/SKILL.md b/skills/foc-cli/SKILL.md index 0b7973d..be3a03a 100644 --- a/skills/foc-cli/SKILL.md +++ b/skills/foc-cli/SKILL.md @@ -99,7 +99,7 @@ If anything in this file ever disagrees with the live `-h`/`--schema` output, tr No RPC or env setup is needed: `getChain()` from `@filoz/synapse-core/chains` bundles the viem chain definition, default Glif RPC endpoints, and every FOC contract address (USDFC, FWSS, Filecoin Pay, PDP verifier, provider registry) for both chains, keyed by chain ID. The CLI's only persistent state is its wallet config file (see Setup). For dApp environment setup (custom RPCs, Next.js env vars, browser wallets), search the live docs instead of guessing: `npx foc-cli docs --prompt "getting started"`. -**Funding:** testnet is one command (`wallet fund`: free tFIL + tUSDFC from faucets). Mainnet has no faucet; real FIL (gas) and USDFC (storage) must be acquired. See [references/mainnet-funding.md](references/mainnet-funding.md) for exchange/bridge/swap/mint routes and the exchange-withdrawal address caveat. +**Funding:** testnet is one command (`wallet fund`: free tFIL + tUSDFC from faucets), with balance checks and documented fallbacks in [references/testnet-funding.md](references/testnet-funding.md). Mainnet has no faucet; real FIL (gas) and USDFC (storage) must be acquired. See [references/mainnet-funding.md](references/mainnet-funding.md) for the user-funded workflow, exchange/bridge/swap/mint routes, and the exchange-withdrawal address caveat. ## Global Options diff --git a/skills/foc-cli/references/mainnet-funding.md b/skills/foc-cli/references/mainnet-funding.md index 1245557..3e5fef3 100644 --- a/skills/foc-cli/references/mainnet-funding.md +++ b/skills/foc-cli/references/mainnet-funding.md @@ -5,6 +5,14 @@ Mainnet (`--chain 314`) uses **real funds**: FIL pays gas, USDFC pays for storag > The live source of truth is the FOC docs — verify before acting: > `npx foc-cli docs --url https://docs.filecoin.cloud/resources/additional-resources.md` +## Agent workflow + +1. Run `npx foc-cli wallet balance --chain 314`, then show the user the public address and the FIL, wallet USDFC, total Filecoin Pay funds, and available Filecoin Pay funds separately. A brand-new address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. +2. Explain that the address needs FIL for gas and USDFC for storage, present the acquisition routes below, and ask the user to fund it. Do not perform an exchange, bridge, swap, or mint for the user. +3. Stop and wait for the user to say funding is complete. +4. Re-run `wallet balance --chain 314` to verify both assets arrived. +5. Run `wallet costs` for the actual upload size, runway, and copy count. Show the estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading. + ## Your wallet address The foc-cli wallet is a standard EVM account (`0x…`) on the Filecoin EVM (FEVM); on Filecoin's native address format it corresponds to an `f410…` address. Get the address from `wallet balance`. **Caveat when withdrawing from exchanges:** not every exchange supports withdrawing FIL directly to `0x`/`f410` addresses. If yours doesn't, withdraw to a self-custody Filecoin wallet that can send to `0x` addresses (e.g. MetaMask with the Filecoin network, or Glif), then forward from there. @@ -34,6 +42,11 @@ For most users storing data, **swapping** (1 or 2) is the right choice; minting ```bash npx foc-cli wallet balance --chain 314 # confirm FIL + USDFC arrived npx foc-cli wallet costs --extraBytes --extraRunway --chain 314 # live rate + deposit needed +``` + +Show the estimate and wait for explicit human confirmation. Only then continue: + +```bash npx foc-cli wallet deposit --chain 314 # move USDFC into the payment account npx foc-cli upload ./file.pdf --chain 314 ``` @@ -42,4 +55,4 @@ Cross-check the USDFC token you received against the address foc-cli itself uses ## Testnet (for contrast) -On Calibration (the default chain) all of this is one command — `npx foc-cli wallet fund` — which claims free tFIL and tUSDFC from faucets. +For the Calibration workflow and documented faucet fallbacks, see [testnet-funding.md](testnet-funding.md). diff --git a/skills/foc-cli/references/testnet-funding.md b/skills/foc-cli/references/testnet-funding.md new file mode 100644 index 0000000..5b2041c --- /dev/null +++ b/skills/foc-cli/references/testnet-funding.md @@ -0,0 +1,45 @@ +# Calibration Funding: Getting tFIL and tUSDFC + +Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payments. Both are test tokens. + +> The live source of truth is the FOC docs — verify before acting: +> `npx foc-cli docs --url https://docs.filecoin.cloud/resources/additional-resources.md` + +## Agent workflow + +1. Inspect the address and current state: + + ```bash + npx foc-cli wallet balance --chain 314159 + ``` + + Report the address, tFIL (`fil`), wallet tUSDFC (`usdfc`), total Filecoin Pay funds (`funds`), and currently available Filecoin Pay funds (`availableFunds`) separately. A brand-new, unfunded address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. + +2. Use the user's funding choice if it is already known. Otherwise, ask whether the user wants to fund the address or wants agent-assisted faucet funding. + + - **User-funded:** show the address and the documented faucets below, then stop and wait. + - **Agent-assisted:** run the built-in faucet command once: + + ```bash + npx foc-cli wallet fund --chain 314159 + ``` + +3. Whether `wallet fund` succeeds, fails, or times out, re-check the balance before deciding what happened: + + ```bash + npx foc-cli wallet balance --chain 314159 + ``` + + One faucet asset may have arrived even when the combined command reports an error. If a returned transaction is pending, or the command failed or timed out without a definitive per-asset result, treat a zero balance as unconfirmed: wait and re-check, then stop rather than submitting another claim. Use a fallback only for an asset known not to have been claimed or confirmed, and never submit a duplicate claim. + +4. After wallet tFIL and tUSDFC are present, run `wallet costs` for the actual upload size, runway, and copy count. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances. + +## Documented fallback ladder + +Use browser handoff for these faucets; the user enters only the public wallet address and completes any human verification: + +1. **Missing tFIL:** use the [ChainSafe Calibration faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html). If it is unavailable, Filecoin Docs also lists the [Zondax faucet](https://beryx.zondax.ch/faucet/) and [Forest faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet). +2. **Missing tUSDFC:** use the [Calibration tUSDFC faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc). +3. Re-run `wallet balance --chain 314159` after each completed request and resume only from the observed balances. + +Do not infer or call faucet APIs from website code, bypass CAPTCHA or anti-bot controls, submit parallel faucet claims, or retry without first checking balances. Never ask for or enter the user's private key into a faucet. From caa77ee75001b641e4144753c317cdb213c4410f Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 12:58:33 -1000 Subject: [PATCH 2/9] docs(skill): quote before requesting mainnet funds --- skills/foc-cli/references/mainnet-funding.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/foc-cli/references/mainnet-funding.md b/skills/foc-cli/references/mainnet-funding.md index 3e5fef3..7ae32b7 100644 --- a/skills/foc-cli/references/mainnet-funding.md +++ b/skills/foc-cli/references/mainnet-funding.md @@ -8,10 +8,10 @@ Mainnet (`--chain 314`) uses **real funds**: FIL pays gas, USDFC pays for storag ## Agent workflow 1. Run `npx foc-cli wallet balance --chain 314`, then show the user the public address and the FIL, wallet USDFC, total Filecoin Pay funds, and available Filecoin Pay funds separately. A brand-new address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. -2. Explain that the address needs FIL for gas and USDFC for storage, present the acquisition routes below, and ask the user to fund it. Do not perform an exchange, bridge, swap, or mint for the user. -3. Stop and wait for the user to say funding is complete. -4. Re-run `wallet balance --chain 314` to verify both assets arrived. -5. Run `wallet costs` for the actual upload size, runway, and copy count. Show the estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading. +2. Run `wallet costs` for the actual upload size, runway, and copy count. Use `alreadyCovered` and `depositNeeded` to determine whether the existing Filecoin Pay funds cover the upload. +3. Explain only the shortfalls: FIL is required for gas, but wallet USDFC is required only when the quote needs an additional payment-account deposit. If `alreadyCovered` is true, do not ask the user to acquire more USDFC. Present acquisition routes only for missing assets, and do not perform an exchange, bridge, swap, or mint for the user. +4. If funding is required, ask the user to fund the displayed address, then stop and wait. Re-run `wallet balance --chain 314` and `wallet costs` after the user says funding is complete. +5. Show the latest estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading. ## Your wallet address @@ -37,7 +37,7 @@ USDFC is a FIL-collateralized, USD-pegged stablecoin by Secured Finance ([docs]( For most users storing data, **swapping** (1 or 2) is the right choice; minting (3) is a DeFi position, not just a purchase. -## After funding +## After any required funding ```bash npx foc-cli wallet balance --chain 314 # confirm FIL + USDFC arrived From c3aa5519e6abb2bfb9403cd47f014ab0c8d1d215 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:05:32 -1000 Subject: [PATCH 3/9] docs(skill): avoid duplicate partial-wallet claims --- skills/foc-cli/references/testnet-funding.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/skills/foc-cli/references/testnet-funding.md b/skills/foc-cli/references/testnet-funding.md index 5b2041c..2820b34 100644 --- a/skills/foc-cli/references/testnet-funding.md +++ b/skills/foc-cli/references/testnet-funding.md @@ -18,13 +18,16 @@ Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payment 2. Use the user's funding choice if it is already known. Otherwise, ask whether the user wants to fund the address or wants agent-assisted faucet funding. - **User-funded:** show the address and the documented faucets below, then stop and wait. - - **Agent-assisted:** run the built-in faucet command once: + - **Agent-assisted, both assets missing:** run the built-in faucet command once: ```bash npx foc-cli wallet fund --chain 314159 ``` -3. Whether `wallet fund` succeeds, fails, or times out, re-check the balance before deciding what happened: + - **Only one asset missing:** do not run the combined command; use the matching asset-specific browser handoff below. + - **Neither asset missing:** skip funding. + +3. After any faucet attempt, re-check the balance before deciding what happened: ```bash npx foc-cli wallet balance --chain 314159 From 08faf2af4d739acb9f7319864ebfaedd28477b82 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:13:42 -1000 Subject: [PATCH 4/9] docs(skill): check testnet payment coverage first --- skills/foc-cli/references/testnet-funding.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/skills/foc-cli/references/testnet-funding.md b/skills/foc-cli/references/testnet-funding.md index 2820b34..b318949 100644 --- a/skills/foc-cli/references/testnet-funding.md +++ b/skills/foc-cli/references/testnet-funding.md @@ -15,19 +15,21 @@ Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payment Report the address, tFIL (`fil`), wallet tUSDFC (`usdfc`), total Filecoin Pay funds (`funds`), and currently available Filecoin Pay funds (`availableFunds`) separately. A brand-new, unfunded address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. -2. Use the user's funding choice if it is already known. Otherwise, ask whether the user wants to fund the address or wants agent-assisted faucet funding. +2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to determine whether Filecoin Pay needs more tUSDFC. If `alreadyCovered` is true, do not request wallet tUSDFC. Otherwise, compare `depositNeeded` with the wallet tUSDFC balance and request only the shortfall. + +3. Use the user's funding choice if it is already known. Otherwise, ask whether the user wants to fund the address or wants agent-assisted faucet funding. - **User-funded:** show the address and the documented faucets below, then stop and wait. - - **Agent-assisted, both assets missing:** run the built-in faucet command once: + - **Agent-assisted, tFIL and tUSDFC both required:** run the built-in faucet command once: ```bash npx foc-cli wallet fund --chain 314159 ``` - - **Only one asset missing:** do not run the combined command; use the matching asset-specific browser handoff below. - - **Neither asset missing:** skip funding. + - **Only one asset required:** do not run the combined command; use the matching asset-specific browser handoff below. + - **Neither asset required:** skip funding. -3. After any faucet attempt, re-check the balance before deciding what happened: +4. After any faucet attempt, re-check the balance before deciding what happened: ```bash npx foc-cli wallet balance --chain 314159 @@ -35,7 +37,7 @@ Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payment One faucet asset may have arrived even when the combined command reports an error. If a returned transaction is pending, or the command failed or timed out without a definitive per-asset result, treat a zero balance as unconfirmed: wait and re-check, then stop rather than submitting another claim. Use a fallback only for an asset known not to have been claimed or confirmed, and never submit a duplicate claim. -4. After wallet tFIL and tUSDFC are present, run `wallet costs` for the actual upload size, runway, and copy count. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances. +5. After any required funding arrives, re-run `wallet costs`. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances. ## Documented fallback ladder From 0933bc234a15bdfa18cadb0c4659b58a053e374d Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:19:44 -1000 Subject: [PATCH 5/9] docs(skill): skip covered mainnet deposits --- skills/foc-cli/references/mainnet-funding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/foc-cli/references/mainnet-funding.md b/skills/foc-cli/references/mainnet-funding.md index 7ae32b7..46d7da5 100644 --- a/skills/foc-cli/references/mainnet-funding.md +++ b/skills/foc-cli/references/mainnet-funding.md @@ -44,10 +44,10 @@ npx foc-cli wallet balance --chain 314 # confirm FIL + USDFC arr npx foc-cli wallet costs --extraBytes --extraRunway --chain 314 # live rate + deposit needed ``` -Show the estimate and wait for explicit human confirmation. Only then continue: +Show the estimate and wait for explicit human confirmation. Run `wallet deposit` only when `depositNeeded` is non-zero; otherwise skip it. Then obtain confirmation for the upload: ```bash -npx foc-cli wallet deposit --chain 314 # move USDFC into the payment account +npx foc-cli wallet deposit --chain 314 # only when depositNeeded is non-zero npx foc-cli upload ./file.pdf --chain 314 ``` From 405ee1e602a5f00ee99432ad8197a44c30802389 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:23:54 -1000 Subject: [PATCH 6/9] docs(skill): wait before faucet fallback --- skills/foc-cli/references/testnet-funding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/foc-cli/references/testnet-funding.md b/skills/foc-cli/references/testnet-funding.md index b318949..ea92a1c 100644 --- a/skills/foc-cli/references/testnet-funding.md +++ b/skills/foc-cli/references/testnet-funding.md @@ -35,7 +35,7 @@ Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payment npx foc-cli wallet balance --chain 314159 ``` - One faucet asset may have arrived even when the combined command reports an error. If a returned transaction is pending, or the command failed or timed out without a definitive per-asset result, treat a zero balance as unconfirmed: wait and re-check, then stop rather than submitting another claim. Use a fallback only for an asset known not to have been claimed or confirmed, and never submit a duplicate claim. + One faucet asset may have arrived even when the combined command reports an error. After the combined command, treat any zero balance as unconfirmed even if the command reported success: wait and re-check after a delay, then stop rather than submitting another claim. Use a fallback only for an asset known not to have been claimed or confirmed, and never submit a duplicate claim. 5. After any required funding arrives, re-run `wallet costs`. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances. From 1c4f7867308003af4e6053ac49097f07d3a7ab7c Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:25:20 -1000 Subject: [PATCH 7/9] docs(skill): align mainnet quote options --- skills/foc-cli/references/mainnet-funding.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/foc-cli/references/mainnet-funding.md b/skills/foc-cli/references/mainnet-funding.md index 46d7da5..6232848 100644 --- a/skills/foc-cli/references/mainnet-funding.md +++ b/skills/foc-cli/references/mainnet-funding.md @@ -8,7 +8,7 @@ Mainnet (`--chain 314`) uses **real funds**: FIL pays gas, USDFC pays for storag ## Agent workflow 1. Run `npx foc-cli wallet balance --chain 314`, then show the user the public address and the FIL, wallet USDFC, total Filecoin Pay funds, and available Filecoin Pay funds separately. A brand-new address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. -2. Run `wallet costs` for the actual upload size, runway, and copy count. Use `alreadyCovered` and `depositNeeded` to determine whether the existing Filecoin Pay funds cover the upload. +2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to determine whether the existing Filecoin Pay funds cover the upload. 3. Explain only the shortfalls: FIL is required for gas, but wallet USDFC is required only when the quote needs an additional payment-account deposit. If `alreadyCovered` is true, do not ask the user to acquire more USDFC. Present acquisition routes only for missing assets, and do not perform an exchange, bridge, swap, or mint for the user. 4. If funding is required, ask the user to fund the displayed address, then stop and wait. Re-run `wallet balance --chain 314` and `wallet costs` after the user says funding is complete. 5. Show the latest estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading. @@ -41,13 +41,13 @@ For most users storing data, **swapping** (1 or 2) is the right choice; minting ```bash npx foc-cli wallet balance --chain 314 # confirm FIL + USDFC arrived -npx foc-cli wallet costs --extraBytes --extraRunway --chain 314 # live rate + deposit needed +npx foc-cli wallet costs --extraBytes --extraRunway --chain 314 [--copies ] [--withCDN] ``` Show the estimate and wait for explicit human confirmation. Run `wallet deposit` only when `depositNeeded` is non-zero; otherwise skip it. Then obtain confirmation for the upload: ```bash -npx foc-cli wallet deposit --chain 314 # only when depositNeeded is non-zero +npx foc-cli wallet deposit --chain 314 # only when depositNeeded is non-zero npx foc-cli upload ./file.pdf --chain 314 ``` From 15a4da51bbf575df9f15062e371da3e6f5ad0b5b Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:32:49 -1000 Subject: [PATCH 8/9] docs(skill): preserve final upload settings --- skills/foc-cli/references/mainnet-funding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/foc-cli/references/mainnet-funding.md b/skills/foc-cli/references/mainnet-funding.md index 6232848..4a77a0e 100644 --- a/skills/foc-cli/references/mainnet-funding.md +++ b/skills/foc-cli/references/mainnet-funding.md @@ -8,7 +8,7 @@ Mainnet (`--chain 314`) uses **real funds**: FIL pays gas, USDFC pays for storag ## Agent workflow 1. Run `npx foc-cli wallet balance --chain 314`, then show the user the public address and the FIL, wallet USDFC, total Filecoin Pay funds, and available Filecoin Pay funds separately. A brand-new address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero. -2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to determine whether the existing Filecoin Pay funds cover the upload. +2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to estimate the initial funding requirement. This is not the final quote: upload re-quotes after selecting providers and may require additional funding. 3. Explain only the shortfalls: FIL is required for gas, but wallet USDFC is required only when the quote needs an additional payment-account deposit. If `alreadyCovered` is true, do not ask the user to acquire more USDFC. Present acquisition routes only for missing assets, and do not perform an exchange, bridge, swap, or mint for the user. 4. If funding is required, ask the user to fund the displayed address, then stop and wait. Re-run `wallet balance --chain 314` and `wallet costs` after the user says funding is complete. 5. Show the latest estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading. @@ -48,7 +48,7 @@ Show the estimate and wait for explicit human confirmation. Run `wallet deposit` ```bash npx foc-cli wallet deposit --chain 314 # only when depositNeeded is non-zero -npx foc-cli upload ./file.pdf --chain 314 +npx foc-cli upload ./file.pdf --chain 314 [--copies ] [--withCDN] ``` Cross-check the USDFC token you received against the address foc-cli itself uses — the CLI's bundled chain config (from `@filoz/synapse-core`) pins the official USDFC contract per chain, so a mismatched balance in `wallet balance` means you hold a different token than the one FOC pays with. From ff44b201a444ddd9eff5134fe8ca557fbe25672f Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 19:30:50 -1000 Subject: [PATCH 9/9] docs(skill): follow per-asset faucet statuses --- skills/foc-cli/references/testnet-funding.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/foc-cli/references/testnet-funding.md b/skills/foc-cli/references/testnet-funding.md index ea92a1c..210681c 100644 --- a/skills/foc-cli/references/testnet-funding.md +++ b/skills/foc-cli/references/testnet-funding.md @@ -29,13 +29,17 @@ Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payment - **Only one asset required:** do not run the combined command; use the matching asset-specific browser handoff below. - **Neither asset required:** skip funding. -4. After any faucet attempt, re-check the balance before deciding what happened: +4. After `wallet fund`, read `fil.status` and `usdfc.status` separately. The top-level `status` is only a summary; do not infer both asset outcomes from it or from one combined error. - ```bash - npx foc-cli wallet balance --chain 314159 - ``` + - **`funded`:** the faucet transaction succeeded and a positive balance was observed. Do not request that asset again. + - **`missing`:** the asset was not funded. If it is still required, use only its matching documented fallback below. + - **`unconfirmed`:** the submission, receipt, or balance check is still uncertain. Do not retry or use another faucet yet. Check any returned `txHash`, wait, then run: + + ```bash + npx foc-cli wallet balance --chain 314159 + ``` - One faucet asset may have arrived even when the combined command reports an error. After the combined command, treat any zero balance as unconfirmed even if the command reported success: wait and re-check after a delay, then stop rather than submitting another claim. Use a fallback only for an asset known not to have been claimed or confirmed, and never submit a duplicate claim. + If the balance appears, continue without another claim. If it remains zero, report the unknown outcome and stop rather than risking a duplicate claim. 5. After any required funding arrives, re-run `wallet costs`. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances.