docs: add Arc contract deployment notes

[westkite1201]

Summary

• Add a contract deployment guide for Arc Testnet
• Document Arc Testnet chain metadata, RPC, Arcscan explorer URL, and USDC native gas metadata
• Document evmVersion: "paris" for Solidity/Foundry deployments to avoid newer-opcode compatibility issues
• Add a Hardhat @nomicfoundation/hardhat-verify customChains example for Arcscan/Blockscout verification

Related issues

• Addresses docs: Arcscan (Blockscout) smart contract source verification undocumented — hardhat-verify customChains configuration missing #84
• Addresses docs: confirmed — Arc Testnet rejects PUSH0 opcode; must use evmVersion: paris; two-immutable constructor (0x60c0) also silently reverts #109

Validation

• npx prettier --check README.md docs/deploying-contracts.md
• git diff --check

[osr21]

Here's what we found deploying and verifying three contracts on Arc Testnet with Foundry — happy to have any of this incorporated.

---

Foundry config (foundry.toml)

[profile.default]
solc          = "0.8.20"
evm_version   = "paris"   # REQUIRED — Arc does not support post-Paris opcodes (PUSH0 etc.)
optimizer     = true
optimizer_runs = 200
via_ir        = true       # needed if any contract hits the stack-depth limit

[rpc_endpoints]
arc_testnet = "https://rpc.testnet.arc.network"

evm_version = "paris" is mandatory. The default (shanghai/cancun) emits PUSH0 opcodes that Arc does not support. The deploy tx will succeed but the bytecode will be invalid.

---

Deploy

forge script script/Deploy.s.sol:Deploy \
  --rpc-url https://rpc.testnet.arc.network \
  --private-key "$DEPLOYER_PRIVATE_KEY" \
  --broadcast --config-path foundry.toml

Deployer wallet needs Arc Testnet USDC (also the native gas token). Get it at https://faucet.circle.com.

---

Arcscan source verification (Blockscout)

forge verify-contract \
  --verifier blockscout \
  --verifier-url "https://testnet.arcscan.app/api/" \
  --compiler-version 0.8.20 --chain 5042002 \
  <ADDRESS> src/<Contract>.sol:<Contract>

For contracts with constructor args:

  --constructor-args $(cast abi-encode "constructor(address,address)" <ARG1> <ARG2>)

---

Arcscan display tip

Add address public owner = msg.sender; to your contract. Blockscout reads this and shows it prominently in the contract overview — useful for anyone auditing on-chain.

---

Arc Testnet quick-reference

Item	Value
Chain ID	5042002 (0x4cef52)
RPC	https://rpc.testnet.arc.network
Explorer	https://testnet.arcscan.app
USDC (native gas)	0x3600000000000000000000000000000000000000
EURC	0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a
CCTP Domain	26
TokenMessengerV2	0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA
MessageTransmitterV2	0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275

Reference implementation with full deploy + verify setup: osr21/arc-stablecoin-dapp.

[osr21]

The updated doc incorporates the earlier deployment notes well. A few remaining gaps from our deployment experience that are worth adding:

---

1. forge verify-contract needs --evm-version paris

The current verify commands are:

forge verify-contract \
  --verifier blockscout \
  --verifier-url "https://testnet.arcscan.app/api/" \
  --compiler-version 0.8.20 \
  --chain 5042002 \
  <contract-address> src/<Contract>.sol:<Contract>

Blockscout recompiles the submitted source to confirm the bytecode matches what's on-chain. Without --evm-version paris, the Blockscout recompile uses a newer EVM target, emits PUSH0 or other post-Paris opcodes, and produces different bytecode — so verification fails with a bytecode mismatch. Add --evm-version paris to both verify examples:

forge verify-contract \
  --verifier blockscout \
  --verifier-url "https://testnet.arcscan.app/api/" \
  --compiler-version 0.8.20 \
  --evm-version paris \
  --chain 5042002 \
  <contract-address> src/<Contract>.sol:<Contract>

This is the most common reason Arcscan verification silently succeeds (returns 200) but the contract never shows as verified.

---

2. Arc native USDC has a decimal split — the quick-reference table should note it

The table lists Native USDC / gas | 0x3600...0000 but doesn't mention the split:

• ERC-20 interface (transfers, approvals, balances) — 6 decimals, same as Circle USDC on every other chain
• Native gas accounting (block explorer display, eth_getBalance) — 18 decimals

Calling transfer(recipient, 1_000_000) moves 1 USDC, not 0.000000000001 USDC. This is correct and expected — but developers who inspect a wallet's gas balance in the explorer and then try to replicate that value in an ERC-20 call will get the arithmetic wrong. A one-line note in the table or a dedicated note below it would save integrators a lot of debugging:

| Native USDC / gas | 0x3600000000000000000000000000000000000000 — 6 decimals for ERC-20 calls, 18 for native gas |

---

3. via_ir = true should be marked optional

As currently written, via_ir = true is in [profile.default] with only a comment saying it's "useful when your contract hits Solidity's stack-depth limit." Readers will include it in every project config by default. It should be called out as optional more explicitly — it can increase compile time by 5–10× on larger contracts and changes code-generation behaviour in ways that occasionally surface edge-case bugs. Suggested change:

# via_ir = true  # Uncomment only if your contract hits the stack-depth limit.
                 # Significantly increases compile time.

---

4. --compiler-version should note it must match the actual build

Both verify examples hardcode --compiler-version 0.8.20. If a developer follows the Hardhat config at the top of the doc (which uses 0.8.24) and then copies the Foundry verify command, verification will fail with a version mismatch. Worth adding a note: "Replace 0.8.20 with the Solidity version that was used to compile the contract — it must match exactly."

[osr21]

All four points addressed:

• --evm-version paris added to both verify commands — Blockscout recompiles will now match the deployed bytecode
• Decimal split documented clearly below the table — the 6-decimal ERC-20 / 18-decimal native gas distinction is the most common arithmetic footgun for Arc integrators
• via_ir commented out with an explicit "uncomment only if needed" note — readers will no longer include it by default
• --compiler-version note added — version mismatch is now called out as the failure mode

Doc is in good shape. No further issues from this review thread.

[osr21]

Findings from Arc Relay Bridge deployment (Paymaster, GasRelayer, FeeRouter, YieldVault — all four chains)

This issue covers the deployment guide gap well. Adding three hard-won findings from deploying four contracts across Arc Testnet, Sepolia, Base Sepolia, and Fuji that aren't documented anywhere and each cost significant debug time.

---

1. evmVersion: "paris" is required — and the failure mode is a silent revert

^0.8.20 defaults to evmVersion: "shanghai", which emits PUSH0 (opcode 0x5f). Arc Testnet's EVM doesn't recognise PUSH0, so the deploy transaction is accepted by the mempool, included in a block, but the constructor silently reverts — you get a contract address back but zero bytecode at it. eth_getCode returns 0x.

The fix is one line in your Hardhat/Foundry config:

// hardhat.config.ts
solidity: {
  version: "0.8.20",
  settings: {
    optimizer: { enabled: true, runs: 200 },
    evmVersion: "paris",   // ← required for Arc, Fuji — prevents PUSH0 emission
  }
}

# foundry.toml
evm_version = "paris"

The same constraint applies to Avalanche Fuji (also rejects PUSH0). Worth calling out in the deployment guide for both chains.

---

2. Contracts with two immutable variables silently revert on Arc (and Base/Fuji)

This one is subtle. When a Solidity contract has two or more immutable variables the compiler generates a 0x60c0 init-code prefix (2-slot layout). Arc's execution environment silently reverts this constructor — same symptom as above: transaction lands, no bytecode at the resulting address.

The workaround: keep your second variable as constant instead of immutable if it never changes per deployment.

// ❌ silently reverts on Arc, Base Sepolia, Fuji
address public immutable usdc;
address public immutable entryPoint;

// ✅ works on all chains
address public immutable usdc;
address public constant ENTRY_POINT = 0x0000000071727De22E5E9d8BAf0edAc6f37da032;

The ERC-4337 EntryPoint address is the same on every EVM chain, so promoting it to constant is semantically equivalent and fixes the deploy.

Root cause: the 0x60c0 init pattern uses a 2-slot reserved area that Arc's (and some other chains') EVM rejects at contract creation. The 0x60a0 single-immutable init pattern works fine.

---

3. testnet.arcscan.app contract verification API does not work (programmatic path is broken)

The deployment guide mentions Hardhat's @nomicfoundation/hardhat-verify with a custom chain entry for Arcscan. We tried every standard format and none work:

Format	Endpoint	Result
Flat source (v1)	POST /api?module=contract&action=verifysourcecode	"Missing codeformat field" — even when codeformat is present
JSON body (v2)	POST /api/v2/smart-contracts/{addr}/verification/via/flattened-code	"Bad request"
Multipart file (v2)	same v2 endpoint with -F files[]=@...	"Bad request"
hardhat verify	uses v1 under the hood	same "Missing codeformat field"
forge verify-contract	Blockscout-compatible mode	same v1 failure

The only working path is the Arcscan UI (Contract → Verify & Publish → Solidity single file). This doesn't scale for multi-contract or multi-chain deployments.

Either the Blockscout instance at testnet.arcscan.app has verification disabled at the API layer, or it expects a non-standard field that isn't documented. Would be helpful to:

• Confirm whether programmatic API verification is intentionally disabled
• If not, expose the correct field names / format
• Add a verifyOnBlockscout Hardhat plugin config example that actually works