English version: /en/doc/introduction.html

What is Kasane

TL;DR

Kasane は、ICP canister 上で EVM実行を提供するプロジェクトです。
公開導線は「canister Candid API」と「Gateway JSON-RPC」です。
JSON-RPCは Ethereum完全互換ではなく、開発用途の制限付き互換です。
互換ターゲットは Ethereum JSON-RPC + EVM実行意味論で、OP/Superchain互換は非目標です。

できること

Ethereum風 JSON-RPC で基本的な参照/送信を行う
canister query/update で直接EVM機能を呼ぶ
indexer で export_blocks を pull し、Postgresへ保持する

主な制約（現行実装）

Ethereum JSON-RPC 互換は制限付き（未対応メソッドは互換仕様ページを参照）
node運用向けワークフローの提供（本書対象外）

互換の立ち位置

明示対象: Ethereum JSON-RPC 互換（制限付き）
非目標: OP-stack / Superchain 互換
注意: eth_sendRawTransaction の成功は submit成功のみ。実行成功は receipt status=0x1 で判定

読者対象

EVM dApp開発者
スマートコントラクト開発者
バックエンド統合開発者
indexer開発者

根拠

README.md（運用サマリ、互換方針）
tools/rpc-gateway/README.md（Gatewayの互換表）
crates/ic-evm-wrapper/evm_canister.did（公開I/F）

互換仕様の正本

JSON-RPC互換ポリシーの正本: ./rpc/overview.md
メソッド差分の詳細: ./compatibility/json-rpc-deviations.md

English version: /en/doc/quickstart.html

Quickstart (Gateway + Candid)

TL;DR

既定ネットワークは public testnet（chain_id=4801360、RPC: https://rpc-testnet.kasane.network）。
導線は2つ: Path A（Gateway JSON-RPC）/ Path B（canister Candid直呼び）。
送信成功判定は submit結果ではなく eth_getTransactionReceipt.status。
tx_id と eth_tx_hash は別物。
deploy/call は署名済み raw tx を用いた送信手順に統一する。

できること / できないこと

できること

接続確認（chain id / block number）
ネイティブ送金（署名済みraw tx投入）
receipt監視（成功/失敗判定）
query系の状態参照（balance/code/storage/call/estimate）

できないこと（現行）

Ethereum標準の pending/mempool API 前提のフロー（eth_pendingTransactions など）
（補足）canister直呼びでは get_pending(tx_id) による個別追跡は可能
WebSocket購読（eth_subscribe）
eth_getLogs の完全互換（filter制約あり）

互換ポリシー詳細は ./rpc/overview.md と ./compatibility/json-rpc-deviations.md を参照。

前提条件

公開RPC: https://rpc-testnet.kasane.network
chain id: 4801360
canister id（testnet運用値）: 4c52m-aiaaa-aaaam-agwwa-cai
dfx（canister query/updateを使う場合）
Gateway経由で送信する場合は署名済み raw tx を用意

Path A: Gateway JSON-RPC

1) 接続確認

RPC_URL="https://rpc-testnet.kasane.network"

curl -s -X POST "$RPC_URL" -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

curl -s -X POST "$RPC_URL" -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

期待結果:

eth_chainId が 0x4944d0（10進 4801360）
eth_blockNumber が 0x... 形式

2) 送金（署名済み raw tx）

RAW_TX="0x<signed_raw_tx_hex>"

curl -s -X POST "$RPC_URL" -H 'content-type: application/json' \
  --data "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"eth_sendRawTransaction\",\"params\":[\"$RAW_TX\"]}"

期待結果:

result に 0x... tx hash が返る（Gatewayが tx_id から eth_tx_hash を解決）

3) receipt監視（成功判定）

TX_HASH="0x<tx_hash_from_send>"

curl -s -X POST "$RPC_URL" -H 'content-type: application/json' \
  --data "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$TX_HASH\"]}"

判定:

status == 0x1: 実行成功
status == 0x0: 実行失敗（submit成功でも失敗しうる）
result == null: まだ採掘反映前

代表エラー

-32602 invalid params: 引数形式不正
-32001 resource not found: prune境界または対象なし
-32000 state unavailable: migration/corrupt等の状態

落とし穴

eth_sendRawTransaction 成功だけで完了扱いにする
tx_id と eth_tx_hash を混同する

Path B: canister Candid直呼び

1) 接続確認（query）

CANISTER_ID="4c52m-aiaaa-aaaam-agwwa-cai"
NETWORK="ic"

dfx canister call --network "$NETWORK" --query "$CANISTER_ID" rpc_eth_chain_id '( )'
dfx canister call --network "$NETWORK" --query "$CANISTER_ID" rpc_eth_block_number '( )'

2) `submit_ic_tx`（IcSynthetic）

submit_ic_tx は record を受け取る:

to: opt vec nat8（Some時は20 bytes、Noneはcreate）
value: nat
gas_limit: nat64
nonce: nat64
max_fee_per_gas: nat
max_priority_fee_per_gas: nat
data: vec nat8

IcSynthetic では from をpayloadに含めません。
wrapper が msg_caller() と canister_self() を付与して core の TxIn::IcSynthetic に渡し、sender を決定します。

# 例: to=0x...01 / value=0 / gas_limit=500000 / data=""
# 注: fee は現行の最小受理条件（min_gas_price/min_priority_fee）以上に設定する。
TO_BYTES="$(python - <<'PY'
to = bytes.fromhex('0000000000000000000000000000000000000001')
print('; '.join(str(b) for b in to))
PY
)"

dfx canister call --network "$NETWORK" "$CANISTER_ID" submit_ic_tx "(record {
  to = opt vec { $TO_BYTES };
  value = 0 : nat;
  gas_limit = 500000 : nat64;
  nonce = 0 : nat64;
  max_fee_per_gas = 500000000000 : nat;
  max_priority_fee_per_gas = 250000000000 : nat;
  data = vec { };
})"

2.0) `submit_ic_tx` 送信手順

運用は次の順で固定すると事故を減らせます。

送信前に chain/network を確認する
- rpc_eth_chain_id が 4801360 であること
送信元nonceを確認する
- expected_nonce_by_address(20 bytes) を呼び、現在nonceを取得
fee/gasを決める
- rpc_eth_gas_price / rpc_eth_max_priority_fee_per_gas を参照し、下限以上を設定
submit_ic_tx(record) を1回送る
- 返り値 tx_id を保存
実行結果を追跡する
- get_pending(tx_id) で状態確認
- get_receipt(tx_id) が取得できたら status で成功/失敗判定

注意:

submit_ic_tx の成功は「受付成功」です。実行成功は receipt.status で判定してください。
tx_id は内部キーであり、eth_tx_hash とは別です。

2.1) `submit_ic_tx` 検証フロー（重要）

pre-submit guard
- anonymous拒否（auth.anonymous_forbidden）
- migration/cycle状態で write拒否（ops.write.*）
decode/検証
- payloadサイズ/形式
- sender導出失敗は arg.principal_to_evm_derivation_failed
- fee条件不一致は submit.invalid_fee
- nonce不一致は submit.nonce_too_low / submit.nonce_gap / submit.nonce_conflict
正常時は tx_id を返し、採掘は非同期（auto-production）

3) nonce取得

ADDR_BLOB='"\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00"'
dfx canister call --network "$NETWORK" --query "$CANISTER_ID" expected_nonce_by_address "(blob $ADDR_BLOB)"

注意:

expected_nonce_by_address は 20 bytes address のみ受理
32 bytes（bytes32エンコードprincipalの誤投入）には明示エラーを返す

4) raw tx投入（EthSigned）

既存ヘルパー eth_raw_tx を使って raw tx bytes を作る:

CHAIN_ID=4801360
PRIVKEY="<YOUR_PRIVKEY_HEX>"
RAW_TX_BYTES=$(cargo run -q -p ic-evm-core --features local-signer-bin --bin eth_raw_tx -- \
  --mode raw \
  --privkey "$PRIVKEY" \
  --to "0000000000000000000000000000000000000001" \
  --value "0" \
  --gas-price "500000000000" \
  --gas-limit "21000" \
  --nonce "0" \
  --chain-id "$CHAIN_ID")

dfx canister call --network "$NETWORK" "$CANISTER_ID" rpc_eth_send_raw_transaction "(vec { $RAW_TX_BYTES })"

5) `tx_id` 追跡（IcSynthetic）

submit_ic_tx の戻り値は eth_tx_hash ではなく内部キー tx_id です。
追跡は以下を使います。

get_pending(tx_id)（Queued/Included/Dropped/Unknown）
get_receipt(tx_id)（実行結果）

6) `eth_sendRawTransaction` の返却注意（Gateway）

通常は eth_tx_hash が返る。
ただし内部で tx_id -> eth_tx_hash 解決に失敗した場合、-32000（submit succeeded but eth hash is unavailable）を返す。

落とし穴

queryメソッドを update呼び出しして失敗する
address 20bytes要件を満たさない（expected_nonce_by_address）
submit_ic_tx の tx_id を eth_tx_hash と混同する
submit_ic_tx 成功だけで実行成功とみなす

Deploy & Call（運用手順）

前提

bytecode 生成済みであること（data フィールドに deploy bytecode を設定）
署名環境（private key / chain id一致）が準備済みであること
nonce と fee を事前に取得・設定すること

実行フロー

eth_estimateGas で deploy tx の gas を見積もる。
deploy用 raw tx を生成し、eth_sendRawTransaction で送信する。
返却された eth_tx_hash を eth_getTransactionReceipt で追跡する。
receipt.contractAddress にデプロイ先アドレスが入ることを確認する。

根拠

README.md
tools/rpc-gateway/README.md
docs/api/rpc_eth_send_raw_transaction_payload.md
crates/evm-core/src/test_bin/eth_raw_tx.rs
crates/ic-evm-wrapper/evm_canister.did
tools/rpc-gateway/src/handlers.ts
crates/ic-evm-wrapper/src/lib.rs（submit_ic_tx, expected_nonce_by_address）
crates/evm-core/src/chain.rs（TxIn::IcSynthetic, submit検証）

English version: /en/doc/concepts/accounts-keys.html

Accounts & Keys

TL;DR

senderは EthSigned と IcSynthetic で導出経路が異なる。
expected_nonce_by_address は20 bytes address前提。
IcSynthetic は from をpayloadで受け取らず、caller情報から決定される。

できること

Eth signed txの署名senderを使う
Principal由来sender（IcSynthetic）を使う

制約

bytes32風の値を20 bytes addressとして扱う

`EthSigned` と `IcSynthetic` の違い

EthSigned
- 署名済みraw txから sender を復元
- chain id検証を伴う
IcSynthetic
- wrapperが msg_caller() と canister_self() を付与して TxIn::IcSynthetic として投入
- payloadに from を持たない
- sender導出失敗は AddressDerivationFailed 系エラーになる

`IcSynthetic` で必ず押さえる点

submit_ic_tx の入力は Candid record（to/value/gas_limit/nonce/max_fee_per_gas/max_priority_fee_per_gas/data）
内部保存時の canonical bytes は to_flag(0/1) 形式
nonce参照は expected_nonce_by_address を使う
戻り値は eth_tx_hash ではなく tx_id
実行確定は submit時点ではなく、後続blockで receipt 参照して判断する

安全な使い方

callerに対応する20 bytesアドレスを確定する
expected_nonce_by_address で nonce を取る
submit_ic_tx を送る
get_pending(tx_id) / get_receipt(tx_id) で追跡する

pending/mempool運用ポリシーの正本は ../rpc/overview.md を参照。

落とし穴

Principalエンコード値をそのままaddressとして投入する
expected_nonce_by_address に20 bytes以外を渡す
tx_id を eth_tx_hash と同一視する
submit成功を実行成功と誤認する

根拠

crates/ic-evm-wrapper/src/lib.rs（expected_nonce_by_address）
crates/evm-core/src/tx_decode.rs（IcSynthetic / EthSigned）
crates/evm-core/src/chain.rs（TxIn::IcSynthetic）
README.md

English version: /en/doc/concepts/transactions-fees.html

Transactions & Fees

TL;DR

対応tx typeは Legacy/2930/1559、4844/7702は非対応。
feeは base fee + priority fee モデル（制限付き）。

手数料モデル

compute_next_base_fee で次ブロックbase fee更新
compute_effective_gas_price で実効価格を計算

落とし穴

chain id不一致txを送る
priority/max feeの整合条件を満たさない

根拠

crates/evm-core/src/tx_decode.rs
crates/evm-core/src/base_fee.rs
crates/evm-core/src/revm_exec.rs

English version: /en/doc/concepts/blocks-receipts-logs.html

Blocks, Receipts, Logs

TL;DR

block/receipt/log は Candid型として公開される。
receipt には status, gas_used, effective_gas_price, contract_address, logs を含む。

ポイント

logs[].logIndex はブロック内通番
receipt lookup は Found/NotFound/PossiblyPruned/Pruned

落とし穴

pruned履歴を永続参照できる前提で設計する
tx_id と eth_tx_hash の照会経路を混在させる

根拠

crates/ic-evm-wrapper/evm_canister.did
crates/ic-evm-rpc/src/lib.rs
tools/rpc-gateway/src/handlers.ts

English version: /en/doc/concepts/finality-reorg.html

Finality & Reorg

TL;DR

本実装は単一ブロックプロデューサ（sequencer）前提で、reorgを前提とする運用モデルは想定しない。
submitとexecuteは分離されるため、receipt監視が必要。

見え方

eth_sendRawTransaction は投入
実行確定は後続blockで反映

注意点

submit成功時点で状態確定したとみなす
Ethereum L1のfork前提ロジックをそのまま持ち込む

根拠

README.md
tools/rpc-gateway/README.md
crates/ic-evm-wrapper/src/lib.rs

English version: /en/doc/compatibility/ethereum-differences.html

Ethereum Differences

TL;DR

互換対象は Ethereum JSON-RPC + EVM実行意味論（完全互換ではない）。
tx type は Legacy/EIP-2930/EIP-1559 を受理、EIP-4844/EIP-7702 は現状未受理。
opcode は Kasane 独自の追加/改変を行わず、採用中 spec（現状PRAGUE）の範囲に従う。
pending/mempool 系APIは一部未実装（eth_pendingTransactions など）。
canister Candid では get_pending(tx_id) による個別追跡を提供する。
単一ブロックプロデューサ（sequencer）前提で、reorgを前提とする運用モデルは想定しない。

注: pending/mempoolの運用ポリシーの正本は ../rpc/overview.md。

対応範囲

できること

Eth signed tx の投入・実行・receipt参照
eth_call / eth_estimateGas（制限付き）
ブロック/tx/receipt/log の参照

制約がある領域

4844 blob tx / 7702 authorization tx は現状未受理
mempoolやfilter/WebSocket購読は制限付き（互換差分あり）

トランザクション互換

Supported
- Legacy (RLP)
- EIP-2930 (tx_type=1)
- EIP-1559 (tx_type=2)
現在未受理
- EIP-4844 (type=0x03)
- EIP-7702 (type=0x04)

opcode差分

Kasane 独自の opcode 追加/挙動改変は行わない。
実際の有効範囲は revm の採用specに依存し、現行デフォルトは PRAGUE。

feeモデル差分

base_fee は保持され、compute_next_base_fee で更新される。
effective_gas_price は max_fee, max_priority_fee, base_fee から計算。
eth_gasPrice は max(base_fee + max(推定priority,min_priority), min_gas_price) を返す。

finality/reorg差分

単一ブロックプロデューサ（sequencer）前提
auto-production 後ブロックは final 扱い（reorg前提では扱わない）
latest/pending/safe/finalized の一部は head扱いの制約あり

代表エラー

DecodeError::UnsupportedType（4844/7702）
DecodeError::WrongChainId
DecodeError::LegacyChainIdMissing

落とし穴

Ethereum L1と同じ pending/finalityモデルを前提にする
4844/7702 tx を送って互換がある前提で実装する

根拠

crates/evm-core/src/tx_decode.rs
crates/evm-core/tests/phase1_eth_decode.rs
crates/evm-core/src/base_fee.rs
crates/evm-core/src/revm_exec.rs
vendor/revm/crates/handler/src/mainnet_builder.rs
vendor/revm/crates/primitives/src/hardfork.rs
tools/rpc-gateway/README.md
README.md

English version: /en/doc/compatibility/json-rpc-deviations.html

JSON-RPC Deviations

TL;DR

実装済みメソッドは限定される。
eth_getLogs は制約が強いが、blockHash は条件付き対応、topics[0] の OR配列は対応済み。
blockTagはメソッドごとに制約があり、latest 系に加えて earliest/QUANTITY を受理するが historical は多くが非対応。
eth_sendRawTransaction は submit API委譲で、実行成功は receipt で確認する。
eth_feeHistory は対応済み（blockCount は number/QUANTITY/10進文字列を受理）。
eth_gasPrice は base_fee 単体ではなく、受理条件に寄せた推定値を返す。

適用範囲: 本ページはJSON-RPC差分の詳細。全体ポリシーは ../rpc/overview.md を正本とする。

メソッド別差分（要点）

eth_getBalance
- latest/pending/safe/finalized/earliest/QUANTITY を受理
- 実質 historical は exec.state.unavailable または invalid.block_range.out_of_window
eth_getTransactionCount
- latest/pending/safe/finalized/earliest/QUANTITY を受理
- pending は pending nonce
- earliest や過去block nonceは非対応（historical nonce未提供）
eth_getCode
- latest/pending/safe/finalized/earliest/QUANTITY を受理
- 実質 historical は exec.state.unavailable または invalid.block_range.out_of_window
eth_getStorageAt
- latest/pending/safe/finalized/earliest/QUANTITY を受理
- slotは QUANTITY/DATA(32 bytes) 受理
- 実質 historical は exec.state.unavailable または invalid.block_range.out_of_window
eth_call, eth_estimateGas
- latest/pending/safe/finalized/earliest/QUANTITY を受理
- historical execution は非対応（exec.state.unavailable / invalid.block_range.out_of_window）
- 未対応フィールドは -32602
eth_getLogs
- blockHash は条件付き対応（fromBlock/toBlock 併用不可、直近Nブロック走査で解決）
- address 単一のみ
- topics[0] OR配列は対応（最大16件）
- topics[1+] 条件は非対応
- 範囲超過は -32005
eth_feeHistory
- blockCount は number / QUANTITY / 10進文字列を受理
- blockCount <= 256
- pending は現状 latest 同義
eth_maxPriorityFeePerGas
- 観測データ不足時は -32000（state unavailable）
eth_gasPrice
- max(base_fee + max(推定priority,min_priority), min_gas_price) を返す

未対応メソッド

eth_getBlockByHash
eth_newFilter / eth_getFilterChanges / eth_uninstallFilter
eth_subscribe / eth_unsubscribe
eth_pendingTransactions

エラー設計

-32602: invalid params
-32000: state unavailable / execution failed
-32001: resource not found（pruned含む）
-32005: limit exceeded（logs）
（補足）submit内部エラーは -32603 が返る経路あり

落とし穴

標準ノード前提の eth_getLogs filter（address[] や topics[1+]）をそのまま投げる
eth_sendRawTransaction だけで成功確定扱いにする
eth_getLogs の blockHash が常に解決できる前提で使う（走査上限あり）

根拠

tools/rpc-gateway/src/handlers.ts
tools/rpc-gateway/README.md
crates/ic-evm-rpc/src/lib.rs

English version: /en/doc/compatibility/precompiles-system-contracts.html

Precompiles & System Contracts

TL;DR

precompile 失敗は exec.halt.precompile_error として分類される。
Kasane は revm の mainnet precompile set を利用し、独自のアドレス上書きはしていない。
現行実装は SpecId::default = PRAGUE のため、OSAKA追加の 0x0100 (P256VERIFY) はデフォルトでは有効化されない。
opcode差分の解説はこのページの責務外（ethereum-differences.md を参照）。

運用方針

precompile失敗の分類は exec.halt.precompile_error を一次判定に使う。
precompile依存機能は mainnet 投入前に対象パスをスモークして動作を固定化する。

対応precompile（現行デフォルト: PRAGUE）

Address	Name	導入段階	備考
`0x01`	`ECREC`	Homestead	secp256k1 ecrecover
`0x02`	`SHA256`	Homestead
`0x03`	`RIPEMD160`	Homestead
`0x04`	`ID`	Homestead	identity
`0x05`	`MODEXP`	Byzantium	Prague では Berlin gas式が適用
`0x06`	`BN254_ADD`	Byzantium	Istanbul 以降はガス更新版
`0x07`	`BN254_MUL`	Byzantium	Istanbul 以降はガス更新版
`0x08`	`BN254_PAIRING`	Byzantium	Istanbul 以降はガス更新版
`0x09`	`BLAKE2F`	Istanbul
`0x0a`	`KZG_POINT_EVALUATION`	Cancun	現行ビルドで有効（検証バックエンドは `c-kzg` / `blst` / `arkworks`）
`0x0b`	`BLS12_G1ADD`	Prague	EIP-2537
`0x0c`	`BLS12_G1MSM`	Prague	EIP-2537
`0x0d`	`BLS12_G2ADD`	Prague	EIP-2537
`0x0e`	`BLS12_G2MSM`	Prague	EIP-2537
`0x0f`	`BLS12_PAIRING_CHECK`	Prague	EIP-2537
`0x10`	`BLS12_MAP_FP_TO_G1`	Prague	EIP-2537
`0x11`	`BLS12_MAP_FP2_TO_G2`	Prague	EIP-2537

OSAKAで追加されるが、現行デフォルトでは未有効

0x0100 (P256VERIFY, RIP-7212)

実装上の前提

evm-core は Context::mainnet().build_mainnet_with_inspector(...) で revm の mainnet builder をそのまま使う。
mainnet builder 側で EthPrecompiles::new(spec) を使って precompile set が決まる。
SpecId::default() は PRAGUE。

観測可能な事実

実行系エラー分類に PrecompileError が存在
wrapper側で exec.halt.precompile_error にマップされる

安全な使い方

precompile依存機能では、exec.halt.precompile_error を監視/分類してリトライ判定を分離する
precompile前提のdAppでは、mainnet投入前に当該pathをスモークする

落とし穴

ingress検証とruntime precompile責務を混同する
0x0100 (P256VERIFY) を常に有効と誤認する
0x0a (KZG) の検証バックエンド差分（c-kzg / blst / arkworks）を考慮しない

根拠

crates/ic-evm-wrapper/src/lib.rs（exec.halt.precompile_error）
crates/evm-core/src/revm_exec.rs
crates/evm-core/Cargo.toml（revm feature）
vendor/revm/crates/handler/src/mainnet_builder.rs
vendor/revm/crates/primitives/src/hardfork.rs
vendor/revm/crates/precompile/src/lib.rs
vendor/revm/crates/precompile/src/id.rs
vendor/revm/crates/precompile/src/bls12_381_const.rs
vendor/revm/crates/precompile/src/secp256r1.rs

English version: /en/doc/rpc/overview.html

RPC Overview

TL;DR

Gateway は canister Candid API を JSON-RPC 2.0 に変換する層です。
互換は制限付きで、未実装メソッドがあります。
入力不正は主に -32602、状態不整合は -32000/-32001。

対応範囲

web3_*, net_*, eth_* の一部
実装メソッドは handleRpc の switch が正本

主なユースケースと制約

基本参照、call、estimate、raw tx投入に対応
filter/ws/pending は互換差分あり（詳細は各ページ参照）

Pending/Mempoolポリシー

Ethereum互換APIとしての pending/mempool（例: eth_pendingTransactions, eth_subscribe）は現状未実装。
ただし canister Candid には get_pending(tx_id) があり、送信済み tx を個別追跡できる。
送信成功判定は submit戻り値ではなく receipt ベース（status）で行う。
詳細は以下を参照:
- ../quickstart.md
- ../compatibility/json-rpc-deviations.md
- ../compatibility/ethereum-differences.md
- ../concepts/accounts-keys.md
- ../_generated/interfaces.md

根拠

tools/rpc-gateway/src/handlers.ts（handleRpc）
tools/rpc-gateway/README.md
crates/ic-evm-wrapper/src/lib.rs（get_pending）

English version: /en/doc/rpc/chain-and-block.html

Chain & Block Methods

TL;DR

eth_chainId, net_version, eth_blockNumber, eth_getBlockByNumber を提供。
eth_getBlockByNumber は prune範囲で -32001。

メソッド

eth_chainId -> canister rpc_eth_chain_id
net_version -> rpc_eth_chain_id を10進文字列化
eth_blockNumber -> canister rpc_eth_block_number
eth_getBlockByNumber -> canister rpc_eth_get_block_by_number_with_status

blockTag制約

latest/pending/safe/finalized は head扱い
prune済みは resource not found

根拠

tools/rpc-gateway/src/handlers.ts
crates/ic-evm-rpc/src/lib.rs

詳細な制約差分は ../compatibility/json-rpc-deviations.md を参照。

English version: /en/doc/rpc/transactions-and-receipts.html

Transaction & Receipt Methods

TL;DR

tx参照は eth_tx_hash 基準。
receiptは PossiblyPruned/Pruned を明示的に返しうる。

メソッド

eth_getTransactionByHash -> rpc_eth_get_transaction_by_eth_hash
eth_getTransactionReceipt -> rpc_eth_get_transaction_receipt_with_status_by_eth_hash

注意

tx_id は内部キー、外部連携は eth_tx_hash を使う。
内部運用で tx_id を直接引く場合は rpc_eth_get_transaction_receipt_with_status_by_tx_id を使う。
migration/corrupt時は state unavailable エラー。

根拠

tools/rpc-gateway/src/handlers.ts
crates/ic-evm-rpc/src/lib.rs

English version: /en/doc/rpc/state.html

State Methods

TL;DR

eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt を提供。
blockTag は latest/pending/safe/finalized/earliest/QUANTITY を受理するが、historical は多くが制約付き。

メソッド

eth_getBalance -> rpc_eth_get_balance
eth_getTransactionCount -> rpc_eth_get_transaction_count_at
eth_getCode -> rpc_eth_get_code
eth_getStorageAt -> rpc_eth_get_storage_at

主な制約

balance/code/storage: QUANTITY==head 以外の historical は state unavailable / out-of-window になり得る
tx count: pending は pending nonce を返す。earliest / 過去nonce は現状未提供

詳細は ../compatibility/json-rpc-deviations.md と ./overview.md を参照。

根拠

tools/rpc-gateway/src/handlers.ts
crates/ic-evm-rpc/src/lib.rs
tools/rpc-gateway/README.md

English version: /en/doc/rpc/call-estimate-send.html

Call, Estimate, Send

TL;DR

eth_call / eth_estimateGas は callObject制約あり。
eth_estimateGas は gas_used ではなく、成功する最小 gas を返す。
eth_sendRawTransaction は canister submit API委譲。

メソッド

eth_call -> rpc_eth_call_object
eth_estimateGas -> rpc_eth_estimate_gas_object
eth_sendRawTransaction -> rpc_eth_send_raw_transaction

callObject制約

対応キー: to/from/gas/gasPrice/value/data/nonce/maxFeePerGas/maxPriorityFeePerGas/chainId/type/accessList
type=0x0 / 0x2 のみ
feeパラメータ併用ルールあり

送信時の運用

submit成功後に receipt status を必ず監視

根拠

tools/rpc-gateway/README.md
tools/rpc-gateway/src/handlers.ts
crates/ic-evm-rpc/src/lib.rs

English version: /en/doc/rpc/logs.html

Logs

TL;DR

eth_getLogs は rpc_eth_get_logs_paged ベースの制限付き実装。
範囲・filter制約を超えると -32005。

対応パターン

単一address + topic0中心のログ取得
topics[0] の OR配列（最大16件）
blockHash 指定（fromBlock/toBlock 併用なし、走査上限内）

制約

topics[1+] 条件は現状未対応
複数address同時指定は未対応

代表エラー

logs.range_too_large
logs.too_many_results
UnsupportedFilter

根拠

crates/ic-evm-rpc/src/lib.rs（rpc_eth_get_logs_paged）
tools/rpc-gateway/src/handlers.ts

English version: /en/doc/rpc/errors-and-limits.html

Errors & Limits

TL;DR

HTTP側制限（body/batch/depth）とRPC側制限（blockTag/filter/range）の二層で制御。
エラーコードは -32602/-32000/-32001/-32005 が中心。

Gateway HTTP制限

RPC_GATEWAY_MAX_HTTP_BODY_SIZE
RPC_GATEWAY_MAX_BATCH_LEN
RPC_GATEWAY_MAX_JSON_DEPTH

RPCエラー

-32602 invalid params
-32000 state unavailable / execution failed
-32001 resource not found
-32005 limit exceeded

根拠

tools/rpc-gateway/src/server.ts
tools/rpc-gateway/src/handlers.ts
tools/rpc-gateway/src/config.ts

English version: /en/doc/contracts/solidity-vyper-compatibility.html

Solidity/Vyper Compatibility

TL;DR

EVM実行系の基本導線として eth_call / eth_estimateGas / eth_sendRawTransaction を利用できる。
互換の詳細は Gateway の実装・互換表を正本として扱う。

利用可能な主要メソッド

eth_call
eth_estimateGas
eth_sendRawTransaction

参照先

tools/rpc-gateway/README.md
crates/evm-core/src/tx_decode.rs

English version: /en/doc/contracts/tooling.html

Tooling (Hardhat/Foundry/ethers/viem)

TL;DR

ethers/viem/foundry のスモークがリポジトリ内にある。
まず read系 + call/estimate + receipt監視を最小セットにする。

手順（最小）

viem: tools/rpc-gateway/smoke/viem_smoke.ts
ethers: tools/rpc-gateway/smoke/ethers_smoke.ts
foundry: tools/rpc-gateway/smoke/foundry_smoke.sh

落とし穴

revert dataを捨てて原因調査不能になる
tx hash保存なしで監視不能になる

根拠

tools/rpc-gateway/smoke/viem_smoke.ts
tools/rpc-gateway/smoke/ethers_smoke.ts
tools/rpc-gateway/smoke/foundry_smoke.sh

English version: /en/doc/contracts/verification.html

Verification

TL;DR

Verify 機能は Explorer 側で提供される。
事前チェック・鍵ローテーション・監視運用は docs/ops/verify_runbook.md を正本として運用する。

運用手順（概要）

EXPLORER_VERIFY_ENABLED=1 と許可コンパイラの環境変数を設定する。
tools/explorer で npm run verify:preflight を実行し、許可バージョンの solc 可用性を確認する。
POST /api/verify/submit で検証ジョブを投入し、GET /api/verify/status で状態を確認する。

根拠

tools/explorer/README.md
docs/ops/verify_runbook.md

English version: /en/doc/integration/sdks.html

SDKs

TL;DR

専用SDKより、JSON-RPCクライアント（ethers/viem/foundry）利用が主。
canister直呼びは Candid 経由で可能。

根拠

tools/rpc-gateway/package.json
crates/ic-evm-wrapper/evm_canister.did

English version: /en/doc/integration/signing-nonce-retries.html

Signing, Nonce, Retries

TL;DR

nonceは送信前に必ず取得する。
chain idは 4801360 を一致させる。
submit成功後は receipt poll で結果判定する。

推奨手順

sender addressを確定
eth_getTransactionCount または expected_nonce_by_address
fee設定（base fee + priorityを考慮）
eth_sendRawTransaction
eth_getTransactionReceipt をpoll

落とし穴

nonce固定値ハードコード
receipt timeout時に再送して nonce競合

根拠

README.md
tools/rpc-gateway/README.md
crates/ic-evm-wrapper/src/lib.rs

English version: /en/doc/integration/indexer-integration-points.html

Indexer Integration Points

TL;DR

pull起点は export_blocks(cursor,max_bytes)。
logs補助取得は rpc_eth_get_logs_paged。
prune前提で cursor運用を設計する。

根拠

crates/ic-evm-wrapper/evm_canister.did
tools/indexer/README.md
docs/specs/indexer-v1.md

English version: /en/doc/indexer/data-model.html

Data Model

TL;DR

indexerは Postgres-first。
txs, receipts, token_transfers, ops_metrics_samples などを保持。

主要ポイント

receipt_status を txs に保持
token transfer は receipt logsから抽出

根拠

tools/indexer/README.md
tools/indexer/src/db.ts

English version: /en/doc/indexer/resync-pagination-missing-data.html

Resync, Pagination, Missing Data

TL;DR

cursorは block_number/segment/byte_offset のJSON固定。
Err.Pruned 返却時は cursorを補正して継続する設計。

落とし穴

indexer停止中にprune進行して履歴欠落
segment上限不一致で復旧不能

根拠

tools/indexer/README.md
docs/specs/indexer-v1.md
tools/indexer/src/config.ts

English version: /en/doc/indexer/event-decoding-tips.html

Event Decoding Tips

TL;DR

ERC-20 Transfer抽出は topic/data長チェックを厳格に行う。
不正ログは行単位スキップし、全体停止を避ける設計。

根拠

tools/indexer/README.md
tools/indexer/src/decode_receipt.ts

English version: /en/doc/security.html

Security Guide

TL;DR

署名鍵管理、chain id一致、receipt監視が最低ライン。
低fee設定・nonce運用ミス・prune未考慮が典型的事故要因。

安全な使い方

chain id固定（4801360）
nonceは毎回取得
eth_sendRawTransaction 後に receipt判定
gateway制限値を過剰緩和しない

危険な落とし穴

status=0x0 を見落として成功扱い
誤chain idで署名したtxを再送し続ける
prune後参照を永続前提にする

推奨設定

RPC_GATEWAY_MAX_BATCH_LEN を既定範囲で維持
INDEXER_CHAIN_ID を実ネットワークと一致
INDEXER_MAX_SEGMENT を canister仕様と一致

根拠

tools/rpc-gateway/src/config.ts
tools/indexer/src/config.ts
tools/rpc-gateway/README.md
crates/evm-core/tests/phase1_eth_decode.rs

English version: /en/doc/troubleshooting.html

Troubleshooting Guide

TL;DR

まず「入力不正」「state unavailable」「pruned」のどれかを切り分ける。
submitとexecuteを分けて観測する。

代表エラーと対処

invalid params (-32602)
- 原因: address/hash長不正、blockTag不正、callObject制約違反
- 対処: 引数hex長・対応キーを再確認
state unavailable (-32000)
- 原因: migration中、critical_corrupt、実行失敗
- 対処: get_ops_status を確認
resource not found (-32001)
- 原因: pruned範囲、対象なし
- 対処: indexer側履歴を参照
limit exceeded (-32005)
- 原因: logs範囲過大/件数過多
- 対処: ブロック範囲分割

落とし穴

eth_getLogs を大範囲一発で引く
監視なしで再送して nonce競合を増やす

根拠

tools/rpc-gateway/src/handlers.ts
tools/rpc-gateway/README.md
crates/ic-evm-wrapper/src/lib.rs（get_ops_status）

English version: /en/doc/appendix/glossary.html

Glossary

tx_id: canister内部識別子
eth_tx_hash: Ethereum互換hash
IcSynthetic: canister独自tx種別
EthSigned: 署名済みEthereum tx
auto-production: timer駆動の自動ブロック生成
PossiblyPruned: prune境界で存在判定が曖昧な状態
Pruned: prune済みで参照不可

English version: /en/doc/appendix/config-reference.html

Config Reference (User Scope)

TL;DR

開発者がよく触る設定だけを抜粋。

Gateway

EVM_CANISTER_ID（必須）
RPC_GATEWAY_IC_HOST
RPC_GATEWAY_PORT

Indexer

EVM_CANISTER_ID（必須）
INDEXER_DATABASE_URL（必須）
INDEXER_IC_HOST
INDEXER_CHAIN_ID（既定 4801360）
INDEXER_MAX_BYTES

English version: /en/doc/appendix/versioning-compatibility-policy.html

Versioning & Compatibility Policy

TL;DR

互換表の更新正本は Gateway README。
メソッド追加・制約変更時は同一PRで要約更新する運用。

根拠

tools/rpc-gateway/README.md
README.md

English version: /en/doc/_generated/repo-map.html

Repo Map

このページは、Kasane リポジトリの「どこに何があるか」を一次情報だけで整理したものです。

TL;DR

EVM canister本体は Rust workspace の ic-evm-wrapper。
実行ロジックは evm-core、永続化/定数は evm-db、RPC補助は ic-evm-rpc。
外部開発者向け入口は tools/rpc-gateway（HTTP JSON-RPC）と crates/ic-evm-wrapper/evm_canister.did（Candid）。
indexer は tools/indexer（Postgres-first）。

主要ディレクトリ

crates/ic-evm-wrapper
- canisterエントリポイント（#[ic_cdk::query] / #[ic_cdk::update]）
- Candid公開定義（evm_canister.did）
crates/evm-core
- tx decode / submit / produce / call / estimate 実装
- EVM実行とfee計算（revm_exec.rs, base_fee.rs）
crates/evm-db
- stable state、chain constants、runtime defaults、receipt/block/tx型
crates/ic-evm-rpc
- wrapperから呼ばれる RPC補助ロジック（eth系参照/変換）
tools/rpc-gateway
- canister Candid API を Ethereum JSON-RPC 2.0 へ変換
tools/indexer
- export API を pull して Postgresへ保存
scripts
- smoke / predeploy / mainnet deploy 補助
docs
- 運用runbook・仕様メモ（一次情報として参照可能）

エントリポイント

canister build/runtime
- dfx.json の canisters.evm_canister
- crates/ic-evm-wrapper/src/lib.rs
gateway runtime
- tools/rpc-gateway/src/main.ts
- tools/rpc-gateway/src/server.ts
indexer runtime
- tools/indexer/src/main.ts

依存関係の大枠

Rust workspace members
- Cargo.toml [workspace].members
JSON-RPC層の実装責務
- Gateway: request/responseと制限
- canister: state/実行/永続化

非対象（本GitBookで扱わない）

ノード運営（validator/sequencer/full node運用手順）
vendor/ 配下の上流ライブラリ内部詳細

根拠

Cargo.toml（workspace members）
dfx.json（canister package/candid）
icp.yaml（deploy recipe）
crates/ic-evm-wrapper/src/lib.rs（canister entrypoint）
tools/rpc-gateway/src/main.ts（gateway entrypoint）
tools/indexer/README.md（indexer責務）

English version: /en/doc/_generated/interfaces.html

Interfaces

TL;DR

外部I/Fは Candid（canister直呼び）と HTTP JSON-RPC（gateway）の2系統。
JSON-RPCは Ethereum完全互換ではなく、制限付き実装。
eth_sendRawTransaction は submit成功≠実行成功。eth_getTransactionReceipt.status を成功条件にする。
pending/mempool は Ethereum互換APIとしては未対応。送信済み tx の追跡は canister get_pending(tx_id) を使う。

1. Candid API（公開service）

公開定義: crates/ic-evm-wrapper/evm_canister.did

主要query

rpc_eth_chain_id
rpc_eth_block_number
rpc_eth_get_block_by_number
rpc_eth_get_block_by_number_with_status
rpc_eth_get_transaction_by_eth_hash
rpc_eth_get_transaction_by_tx_id
rpc_eth_get_transaction_receipt_by_eth_hash
rpc_eth_get_transaction_receipt_with_status_by_eth_hash
rpc_eth_get_transaction_receipt_with_status_by_tx_id
rpc_eth_get_balance
rpc_eth_get_code
rpc_eth_get_storage_at
rpc_eth_call_object
rpc_eth_call_rawtx
rpc_eth_estimate_gas_object
rpc_eth_get_logs_paged
rpc_eth_get_block_number_by_hash
rpc_eth_gas_price
rpc_eth_max_priority_fee_per_gas
rpc_eth_fee_history
expected_nonce_by_address
get_receipt
get_pending
export_blocks
get_ops_status
health
metrics

主要update

rpc_eth_send_raw_transaction
submit_ic_tx
set_block_gas_limit
set_instruction_soft_limit
set_prune_policy
set_pruning_enabled
set_log_filter
prune_blocks

2. Gateway JSON-RPC

実装: tools/rpc-gateway/src/handlers.ts の handleRpc switch

実装済みメソッド

web3_clientVersion
net_version
eth_chainId
eth_blockNumber
eth_gasPrice
eth_maxPriorityFeePerGas
eth_feeHistory
eth_syncing
eth_getBlockByNumber
eth_getTransactionByHash
eth_getTransactionReceipt
eth_getBalance
eth_getTransactionCount
eth_getCode
eth_getStorageAt
eth_getLogs
eth_call
eth_estimateGas
eth_sendRawTransaction

未対応（READMEの互換表）

eth_getBlockByHash
eth_getTransactionByBlockHashAndIndex
eth_getTransactionByBlockNumberAndIndex
eth_getBlockTransactionCountByHash
eth_getBlockTransactionCountByNumber
eth_newFilter
eth_getFilterChanges
eth_uninstallFilter
eth_subscribe
eth_unsubscribe
eth_pendingTransactions

3. 制約の正本

全体ポリシーの正本: ../rpc/overview.md
JSON-RPC差分の正本: ../compatibility/json-rpc-deviations.md
pending/mempool運用の正本: ../rpc/overview.md の「Pending/Mempoolポリシー」

本ページは「インターフェース一覧」の要約に限定し、詳細な挙動差分は上記正本に集約する。

4. 返却・識別子の注意

canister内部識別子: tx_id
Ethereum互換識別子: eth_tx_hash
Gateway eth_sendRawTransaction は canister戻り tx_id から eth_tx_hash を解決して返す。

5. 型境界（代表）

RpcCallObjectView（Candid）
EthBlockView / EthTxView / EthReceiptView
RpcBlockLookupView（NotFound / Found / Pruned）
RpcReceiptLookupView（NotFound / Found / PossiblyPruned / Pruned）
PendingStatusView（Queued / Included / Dropped / Unknown）

根拠

crates/ic-evm-wrapper/evm_canister.did
tools/rpc-gateway/src/handlers.ts
tools/rpc-gateway/README.md
crates/ic-evm-wrapper/src/lib.rs（get_pending, rpc_eth_send_raw_transaction）

English version: /en/doc/_generated/config-reference.html

Config Reference

TL;DR

必須設定は Gateway: EVM_CANISTER_ID、Indexer: EVM_CANISTER_ID + INDEXER_DATABASE_URL。
既定の chain_id は 4801360。
ガス/採掘/prune の既定値は Rust定数で管理される。

1. Gateway環境変数

定義: tools/rpc-gateway/src/config.ts

必須
- EVM_CANISTER_ID
任意（既定値）
- RPC_GATEWAY_IC_HOST（https://icp-api.io）
- RPC_GATEWAY_FETCH_ROOT_KEY（false）
- RPC_GATEWAY_IDENTITY_PEM_PATH（null）
- RPC_GATEWAY_HOST（127.0.0.1）
- RPC_GATEWAY_PORT（8545）
- RPC_GATEWAY_CLIENT_VERSION（kasane/phase2-gateway/v0.1.0）
- RPC_GATEWAY_MAX_HTTP_BODY_SIZE（262144）
- RPC_GATEWAY_MAX_BATCH_LEN（20）
- RPC_GATEWAY_MAX_JSON_DEPTH（20）
- RPC_GATEWAY_CORS_ORIGIN（*）

2. Indexer環境変数

定義: tools/indexer/src/config.ts

必須
- EVM_CANISTER_ID
- INDEXER_DATABASE_URL
任意（既定値）
- INDEXER_IC_HOST（https://icp-api.io）
- INDEXER_DB_POOL_MAX（10）
- INDEXER_RETENTION_DAYS（90）
- INDEXER_RETENTION_ENABLED（true）
- INDEXER_RETENTION_DRY_RUN（false）
- INDEXER_ARCHIVE_GC_DELETE_ORPHANS（false）
- INDEXER_MAX_BYTES（1200000）
- INDEXER_BACKOFF_INITIAL_MS（200）
- INDEXER_BACKOFF_MAX_MS（5000）
- INDEXER_IDLE_POLL_MS（1000）
- INDEXER_PRUNE_STATUS_POLL_MS（30000）
- INDEXER_OPS_METRICS_POLL_MS（30000）
- INDEXER_FETCH_ROOT_KEY（false）
- INDEXER_ARCHIVE_DIR（./archive）
- INDEXER_CHAIN_ID（4801360）
- INDEXER_ZSTD_LEVEL（3）
- INDEXER_MAX_SEGMENT（2）

3. Chain / Runtime定数

chain constants

定義: crates/evm-db/src/chain_data/constants.rs

CHAIN_ID = 4_801_360
MAX_TX_SIZE = 128 * 1024
MAX_TXS_PER_BLOCK = 1024
MAX_PENDING_GLOBAL = 8192
MAX_PENDING_PER_SENDER = 64
MAX_PENDING_PER_PRINCIPAL = 32
MAX_NONCE_WINDOW = 64
MAX_LOGS_PER_TX = 64
MAX_LOG_TOPICS = 4

runtime defaults

定義: crates/evm-db/src/chain_data/runtime_defaults.rs

DEFAULT_MINING_INTERVAL_MS = 2000
DEFAULT_BASE_FEE = 250_000_000_000
DEFAULT_MIN_GAS_PRICE = 250_000_000_000
DEFAULT_MIN_PRIORITY_FEE = 250_000_000_000
DEFAULT_BLOCK_GAS_LIMIT = 3_000_000
DEFAULT_INSTRUCTION_SOFT_LIMIT = 4_000_000_000
DEFAULT_PRUNE_TIMER_INTERVAL_MS = 3_600_000
DEFAULT_PRUNE_MAX_OPS_PER_TICK = 5_000
MIN_PRUNE_TIMER_INTERVAL_MS = 1_000
MIN_PRUNE_MAX_OPS_PER_TICK = 1

4. 危険値・注意

INDEXER_CHAIN_ID が実チェーンと不一致だと署名/検証系の運用が破綻しうる。
RPC_GATEWAY_MAX_HTTP_BODY_SIZE を過大化すると DoS耐性が下がる。
DEFAULT_MIN_GAS_PRICE / DEFAULT_MIN_PRIORITY_FEE を無根拠で下げると低feeスパム耐性が下がる。

根拠

tools/rpc-gateway/src/config.ts
tools/indexer/src/config.ts
crates/evm-db/src/chain_data/constants.rs
crates/evm-db/src/chain_data/runtime_defaults.rs

English version: /en/doc/_generated/open-questions.html

Open Questions

現在、このドキュメントセット内に保留事項はありません。

Keyboard shortcuts

Kasane Developer Docs