메인 콘텐츠로 건너뛰기
StableNet 테스트넷 개발 중 자주 겪는 오류와 해결 방법을 정리했습니다.

​
”replacement transaction underpriced”

의미: 동일한 nonce로 대기 중인 트랜잭션을 교체하려 했지만, 새 트랜잭션의 수수료가 기존 트랜잭션을 대체하기에 충분하지 않습니다. 해결: --gas-price와 --priority-gas-price 두 값을 높은 레퍼런스 값으로 함께 지정하세요: 
cast send <CONTRACT> "methodName()" \
  --rpc-url https://api.test.stablenet.network \
  --private-key $PRIVATE_KEY \
  --gas-price 80000000000000 \
  --priority-gas-price 35000000000000
Hardhat / ethers.js에서는 두 필드를 명시적으로 지정하세요: 
{
  maxPriorityFeePerGas: ethers.parseUnits("35000", "gwei"), // 35000000000000 wei
  maxFeePerGas: ethers.parseUnits("80000", "gwei"),         // 80000000000000 wei
}
35,000 Gwei / 80,000 Gwei는 StableNet 테스트넷에서 실측된 레퍼런스 값입니다. 공식 프로토콜 스펙이 아니므로 멤풀 상태에 따라 조정하세요.

​
”NativeCoinAdapter: transfer amount exceeds balance”

의미: 지갑 잔액이 전송 금액과 가스 비용을 합산한 값을 감당하지 못합니다. NativeCoinAdapter는 가스와 WKRC 전송에 동일한 잔액을 사용합니다. 해결: 가스 가격을 낮추고 재시도하세요. maxFeePerGas 값이 높으면 가스 예약량이 늘어나 전송에 사용할 잔액이 줄어듭니다. 
cast send $WKRC \
  "approve(address,uint256)" $CONTRACT $AMOUNT \
  --rpc-url https://api.test.stablenet.network \
  --private-key $PRIVATE_KEY \
  --priority-gas-price 27600000000000
WKRC 시스템 컨트랙트 메서드를 호출할 때는 꼭 필요한 경우가 아니면 --priority-gas-price를 27,600 Gwei 이상으로 올리지 마세요. 값이 높을수록 가스 예약량이 증가해 이 오류가 발생할 수 있습니다.

​
트랜잭션 타임아웃 (cast / Hardhat)

의미: cast가 타임아웃 오류를 반환하거나 waitForDeployment() / tx.wait()가 응답 없이 멈춘 것처럼 보입니다. 이는 트랜잭션 실패를 의미하지 않습니다. 대처 방법: 1~2분 기다리세요. 트랜잭션은 이미 멤풀에 있으며, 블록에 포함되면 확인됩니다. StableNet의 블록 타임은 약 1초지만 멤풀 전파에 시간이 걸릴 수 있습니다.
동일한 nonce로 취소 후 재전송하지 마세요. nonce 충돌이 발생해 “replacement transaction underpriced” 오류로 이어질 수 있습니다. Explorer에서 트랜잭션이 대기 중인지 이미 확인됐는지 먼저 확인하세요.

​
maxFeePerGas 미설정으로 트랜잭션 거부

의미: maxPriorityFeePerGas는 설정했지만 maxFeePerGas를 빠뜨렸습니다. StableNet에서는 maxFeePerGas를 지정하지 않으면 0으로 기본 설정되어 우선순위 수수료가 올바르더라도 트랜잭션이 거부됩니다. 해결: 두 필드를 항상 함께 지정하세요: 
const tx = await wallet.sendTransaction({
  to: "0xRecipientAddress",
  value: ethers.parseEther("1.0"),
  maxPriorityFeePerGas: ethers.parseUnits("27600", "gwei"),
  maxFeePerGas: ethers.parseUnits("80000", "gwei"),
});

​
npx hardhat init 실패 또는 예기치 않은 동작

의미: Hardhat v3에서 npx hardhat init이 인터랙티브 전용 플로우로 변경되어 일부 환경에서 표준 JavaScript 프로젝트를 정상적으로 생성하지 못할 수 있습니다. 해결: Hardhat v2를 명시적으로 설치하세요: 
npm install --save-dev hardhat@2
npx hardhat init
프롬프트에서 **“Create a JavaScript project”**를 선택하세요. Hardhat v2는 StableNet 테스트넷과 완전히 호환됩니다.

​
Node.js v20+에서 import dotenv/config 오류

의미: Node.js v20 이상에서는 모듈 설정에 따라 import 'dotenv/config' 또는 require('dotenv').config() 사용 시 import 해석 오류가 발생할 수 있습니다. 해결: dotenv 패키지 대신 내장 --env-file 플래그를 사용하세요: 
node --env-file=.env your-script.js
.env 파일 형식은 동일하게 유지됩니다: 
PRIVATE_KEY=your_private_key_here
--env-file 플래그는 Node.js v20.6.0 이상에서 사용할 수 있습니다. 이전 버전을 사용 중이라면 dotenv를 그대로 사용하세요.

​
viem privateKeyToAccount — 잘못된 프라이빗 키

의미: privateKeyToAccount는 0x로 시작하는 16진수 문자열을 요구합니다. .env 파일에 접두사 없이 키를 저장한 경우(예: PRIVATE_KEY=abc123...) viem이 invalid key 오류를 던집니다. 해결: 환경 변수 전달 시 0x를 앞에 추가하세요: 
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
.env 파일에는 0x 접두사 없이 저장하세요: 
PRIVATE_KEY=your64hexcharsprivatekey
반대로 .env에 0x 접두사를 포함해 저장(PRIVATE_KEY=0x...)하고 process.env.PRIVATE_KEY를 바로 전달하는 방식도 괜찮습니다. 프로젝트 내에서 하나의 방식을 일관되게 사용하세요.

​
다음 단계

Foundry 퀵스타트

Foundry로 WKRC 결제 컨트랙트를 배포하세요.

Hardhat 가이드

Hardhat 설정 및 StableNet 컨트랙트 배포.

SDK 가이드

ethers.js 또는 viem으로 WKRC와 연동하세요.