Coming from ethers.js / viem

A translation table from the two JavaScript libraries most readers (human or model) already know to the Cartouche calls that do the same job — and, in the last column, where the semantics differ. Cartouche is not a port of either: it is an idiomatic Elixir substrate that happens to cover the same ground. The differences column is the part worth reading; the name mappings are the part worth searching.

Verified against cartouche 0.9.1 (2026-09-16). ethers refers to v6, viem to 2.x. ABI rows point into hieroglyph, Cartouche's ABI dependency, because that is where the ABI.* modules live.

Read this first — four rules that are not in the table

Bytes, not hex strings. Every address, hash, signature, calldata and return value is a raw binary (<<_::160>> for an address, <<_::256>> for a word). Hex strings exist only at the JSON-RPC boundary and in your own logs. Cartouche.Hex.from_hex!/1 on the way in, Cartouche.Hex.to_hex/1 on the way out — or use Cartouche.Hex and write ~h[0x…]. Passing a "0x…" string where an address is expected does not error early; it produces a 42-byte binary and fails somewhere downstream.
Cartouche.Signer.sign/3 is not signMessage. It keccaks the bytes it is given and signs that digest — no EIP-191 prefix, and v is EIP-155-encoded (chain_id * 2 + 35 + recid) by default, which can exceed one byte. Cartouche.Signer.sign_message/3 is the wallet-compatible form — it adds the prefix and fixes v to 27/28; use it wherever ethers or viem would call signMessage.
A signer is a process, not a value. new Wallet(pk) becomes a supervised Cartouche.Signer GenServer (started from config or Cartouche.Signer.start_link/1), addressed by name or pid through the signer: option. Cartouche.Signer.Curvy is the raw-key backend if you need a function call without a process.
Nothing validates an EIP-55 checksum. Cartouche.Hex.checksum_address/1 produces one; Cartouche.Hex.decode_address!/1 checks length only. ethers' getAddress throws on a wrongly cased input — Cartouche accepts it.

Results are {:ok, value} | {:error, reason} tuples; !-suffixed functions raise. Options are trailing keyword lists. Integers are native arbitrary precision — there is no BigNumber/bigint distinction anywhere.

Bytes and hex

ethers v6	viem	Cartouche	Difference
`getBytes("0x…")`	`hexToBytes`	`Cartouche.Hex.from_hex!/1`, or `~h[0x…]`	—
`hexlify(bytes)`	`bytesToHex`	`Cartouche.Hex.to_hex/1`	always lowercase, always `0x`-prefixed
`toQuantity(n)`	`numberToHex(n)`	`Cartouche.Hex.encode_quantity/1`	— (minimal hex, `"0x0"` for zero)
`toBigInt("0x…")`	`hexToBigInt`	`Cartouche.Hex.decode_hex_number!/1`	returns a plain integer
`zeroPadValue(v, 32)`	`pad(v, { size: 32 })`	`Cartouche.Hex.pad/2`	binaries only; raises if the input is already longer
`zeroPadBytes(v, 32)`	`pad(v, { dir: "right" })`	`Cartouche.Hex.pad_right/2`	—
`dataSlice`, `concat`	`slice`, `concat`	binary pattern matching, `<>`	no helpers — the language does it
`encodeBase58` / `decodeBase58`	—	`Cartouche.Base58.encode/1`, `decode/1`, `decode!/1`	`decode/1` returns `{:ok, bytes}`

Units

ethers v6	viem	Cartouche	Difference
`parseEther("1.5")`	`parseEther("1.5")`	`Cartouche.Wei.to_wei({Decimal.new("1.5"), :eth})`	input is `Decimal` or integer, never a string or float; the atom is `:eth` (`:ether` is rejected); a fraction finer than 1 wei raises — viem rounds, ethers throws
`parseUnits("5", "gwei")`	`parseGwei("5")`	`Cartouche.Wei.to_wei({5, :gwei})`	integer gwei only — there is no `{Decimal, :gwei}` clause
`parseUnits(x, decimals)`	`parseUnits(x, decimals)`	—	no arbitrary-decimals helper; multiply integers yourself
`formatEther`, `formatUnits`	`formatEther`, `formatUnits`	—	not in Cartouche; nothing renders wei back to a decimal string
a `bigint` amount	a `bigint` amount	an integer, or `{n, :wei \| :gwei \| :eth}` anywhere a fee or value is taken	the tagged tuple is accepted by every constructor and by `execute_trx/3` options

Hashing and addresses

ethers v6	viem	Cartouche	Difference
`keccak256(bytes)`	`keccak256(bytes)`	`Cartouche.Hash.keccak/1`	returns 32 raw bytes
`id("Transfer(address,uint256)")`	`toEventSelector` / `keccak256(toBytes(s))`	`Cartouche.Hash.keccak/1` on the string, or `ABI.Event.event_signature/1` from a selector	—
`getAddress("0x…")`	`getAddress`	`Cartouche.Hex.checksum_address/1` (string → string) or `Cartouche.Hex.to_address/1` (bytes → string)	produces EIP-55 but never validates it — see rule 4
`isAddress`	`isAddress`	`Cartouche.Hex.decode_address!/1` (raises otherwise)	length check only, no checksum check
`computeAddress(pubkey)`	`publicKeyToAddress`	`Cartouche.Address.from_public_key/1`	SEC1 uncompressed `0x04‖X‖Y` (65 bytes) only; compressed keys are not accepted
`getCreateAddress`, `getCreate2Address`	`getContractAddress`	—	not in Cartouche

Keys and signers

ethers v6	viem	Cartouche	Difference
`Wallet.createRandom()`	`generatePrivateKey()` + `privateKeyToAccount`	`Cartouche.Keys.generate_keypair/0` → `{address, private_key}`	32 random bytes, no mnemonic (BIP-39/32 is roadmap task 9015)
`new Wallet(pk)`	`privateKeyToAccount(pk)`	config `signer: [default: {:priv_key, "0x…"}]`, or `Cartouche.Signer.start_link(mfa: {Cartouche.Signer.Curvy, :sign, [pk]}, name: MySigner)`	a process — see rule 3; the `:default` entry registers as `Cartouche.Signer.Default` and is what every `signer:`-less call uses
`wallet.address`	`account.address`	`Cartouche.Signer.address/1`	20 raw bytes, fetched from the process
— (address from a key, no object)	`privateKeyToAddress`	`Cartouche.Signer.Curvy.get_address/1`	—
`wallet.signingKey.publicKey`	`privateKeyToAccount(pk).publicKey`	`Cartouche.Signer.Curvy.public_key/1`	—
`signingKey.sign(digest)`	`sign({ hash, privateKey })`	`Cartouche.Signer.Curvy.sign_digest/2`	returns `%Curvy.Signature{}` without a recovery id; `Cartouche.Recover.find_recid_from_digest/3` recovers it against the expected address
a KMS signer (third-party plugins)	`toAccount` with a custom `sign`	`{:cloud_kms, credentials, key_path, version}` signer spec	GCP Cloud KMS is a first-class backend; KMS emits no recovery bit, so Cartouche tries all four

Messages and typed data

ethers v6	viem	Cartouche	Difference
`signer.signMessage(msg)`	`signMessage`	`Cartouche.Signer.sign_message/3`	— (`sign/3` is the unprefixed, EIP-155 primitive — see rule 2)
`hashMessage(msg)`	`hashMessage`	`Cartouche.Hash.keccak(Cartouche.Recover.prefix_eth(msg))`	—
`verifyMessage(msg, sig)`	`recoverMessageAddress` / `verifyMessage`	`Cartouche.Recover.recover_personal_sign/2`	returns the 20-byte address — compare it yourself; accepts packed `r‖s‖v` with `v` in `{0, 1, 27, 28, EIP-155}` or a `%Curvy.Signature{}`
`recoverAddress(digest, sig)`	`recoverAddress`	`Cartouche.Recover.recover_eth_from_digest/2`	—
—	—	`Cartouche.Recover.recover_eth/2`	keccaks the message first and applies no prefix — the inverse of `Cartouche.Signer.sign/3`, with no ethers equivalent
`TypedDataEncoder.encode(d, t, v)`	—	`Cartouche.Typed.encode/1`	same `0x1901 ‖ domainSeparator ‖ hashStruct` bytes
`TypedDataEncoder.hash(d, t, v)`	`hashTypedData`	`Cartouche.Hash.keccak(Cartouche.Typed.encode(typed))`	—
`signer.signTypedData(d, t, v)`	`signTypedData`	`Cartouche.Signer.sign_typed_data/3`	— (`sign/3` on `Typed.encode/1` gives the same digest with an EIP-155 `v`)
`verifyTypedData`	`recoverTypedDataAddress`	`Cartouche.Recover.recover_eth(Cartouche.Typed.encode(typed), sig)`	—
`TypedDataEncoder.hashStruct`	`hashStruct`	`Cartouche.Typed.hash_struct/3`	—
`TypedDataEncoder.hashDomain`	`hashDomain`	`Cartouche.Typed.domain_seperator/1`	note the spelling
`eth_signTypedData_v4` JSON payload	same	`Cartouche.Typed.deserialize/1`	expects `domain` / `types` / `value` keys — a wallet payload's `message` must be renamed; `primaryType` is not read (inferred from `value`'s field names)

Transactions

Cartouche has one struct per envelope type and no field-based type inference: Cartouche.Transaction.V1 (legacy), V_2930 (type 1), V2 (EIP-1559), V3 (EIP-4844), V4 (EIP-7702).

ethers v6	viem	Cartouche	Difference
`Transaction.from({ to, value, … })`	`prepareTransactionRequest`	`Cartouche.Transaction.V2.new(nonce, max_priority_fee, max_fee, gas_limit, to, value, data, access_list, chain_id)`	positional constructor per type, not a request object; pick the struct yourself
`Transaction.from(serialized)`	`parseTransaction`	`Cartouche.Transaction.decode/1`	dispatches on the envelope byte; `{:ok, struct}`
`tx.serialized`	`serializeTransaction`	`Cartouche.Transaction.encode/1`	raw bytes — `to_hex/1` before JSON
`tx.from`	`recoverTransactionAddress`	`Cartouche.Transaction.V2.recover_signer/1`, `V1.recover_signer/2`	V1 needs the chain id passed in
`tx.hash`	`keccak256(serialized)`	`V3.hash/1`, `V4.hash/1`; for V1/V2 `Cartouche.Hash.keccak(Cartouche.Transaction.encode(tx))`	no `hash/1` on V1 and V2
`wallet.signTransaction(tx)`	`signTransaction`	`Cartouche.Transaction.build_signed_trx_v2/9` (builds and signs), `build_signed_trx/7` for legacy; `V3.sign/2`, `V4.sign/2` on an existing struct	V1/V2 have no `sign/2` — the builder is the signing path; its `:callback` option runs between construction and signing
`wallet.sendTransaction(tx)`	`sendTransaction` / `writeContract`	`Cartouche.RPC.execute_trx(to, calldata, opts)`	fetches nonce, fees and gas, runs `eth_call` first (`verify: true` is the default), signs, broadcasts — `simulateContract` + `writeContract` in one call; `Cartouche.RPC.prepare_trx/3` is the same without the broadcast
`provider.broadcastTransaction(raw)`	`sendRawTransaction`	`Cartouche.RPC.send_trx/2` on a signed V1/V2 struct	V3/V4 go through `Cartouche.RPC.send_rpc("eth_sendRawTransaction", [to_hex(raw)])`
`authorization` signing (7702)	`signAuthorization`	`Cartouche.Transaction.V4.sign_authorization/2` on `{chain_id, address, nonce}`	—
an RPC transaction object	same	`Cartouche.Transaction.V2.from_json/1` (and per type)	—

RPC reads

There is no provider or client value: every function takes ethereum_node: url in its trailing opts (defaulting to config :cartouche, :ethereum_node). A client struct is roadmap task 9017 in onchain.

ethers v6	viem	Cartouche	Difference
`new JsonRpcProvider(url)`	`createPublicClient({ transport: http(url) })`	—	`ethereum_node:` option per call, or application config
`provider.send(method, params)`	`client.request({ method, params })`	`Cartouche.RPC.send_rpc/3`	returns the raw JSON value unless `decode: :hex \| :hex_unsigned \| fun`
`getBalance(addr)`	`getBalance`	`Cartouche.RPC.get_balance/2`	integer wei
`getTransactionCount(addr)`	`getTransactionCount`	`Cartouche.RPC.get_nonce/2`	`block_number: "pending"` for the pending nonce
`getCode(addr)`	`getCode` / `getBytecode`	`Cartouche.RPC.get_code/2`	raw bytes
`getStorage(addr, slot)`	`getStorageAt`	—	roadmap task 2130; `send_rpc("eth_getStorageAt", …)` until then
`getBlockNumber()`	`getBlockNumber`	`Cartouche.RPC.eth_block_number/1`	—
`getNetwork().chainId`	`getChainId`	`Cartouche.RPC.eth_chain_id/1`	—
`getBlock(tag, prefetchTxs)`	`getBlock`	`Cartouche.RPC.get_block_by_number/2`, `get_block_by_hash/2` → `%Cartouche.Block{}`	`include_transaction_details: true` for full transactions
`getTransactionReceipt(hash)`	`getTransactionReceipt`	`Cartouche.RPC.get_trx_receipt/2` → `%Cartouche.Receipt{} \| nil`	—
`getTransaction(hash)`	`getTransaction`	—	roadmap task 2129; `send_rpc("eth_getTransactionByHash", …)` until then
`waitForTransaction(hash)`	`waitForTransactionReceipt`	—	roadmap task 9017
`getFeeData()`	`estimateFeesPerGas`	`Cartouche.RPC.gas_price/1`, `max_priority_fee_per_gas/1`, `base_fee/1`, `fee_history/1` → `%Cartouche.FeeHistory{}`	no combined fee struct; `execute_trx/3` derives fees itself (`base_fee_buffer`, `priority_fee` options)
`estimateGas(tx)`	`estimateGas`	`Cartouche.RPC.estimate_gas/2`	takes a V1/V2/`%Cartouche.Transaction.Call{}` struct
`call(tx)`	`call`	`Cartouche.RPC.call_trx/2`	returns raw return bytes; a revert is `{:error, %{code: 3, message: _, revert: bytes}}`, decoded when `errors: ["MyError(uint256)"]` is passed
—	`createAccessList`	`Cartouche.RPC.create_access_list/2`	—
`getLogs(filter)`	`getLogs`	—	roadmap task 2128; node-side filters only (below), or `send_rpc`, until then
`FallbackProvider`	`fallback([...])`	—	roadmap task 9014
—	—	`Cartouche.RPC.debug_trace_call/2`, `trace_call/2`, `trace_call_many/2`, `trace_trx/2`	typed tracing wrappers, first-class

Contract calls (ABI lives in hieroglyph)

ethers v6	viem	Cartouche / hieroglyph	Difference
`new Interface(abiJson)`	`abi` array	`ABI.parse_specification/1`	—
`Fragment.from("function transfer(address,uint256)")`	`parseAbiItem`	`ABI.FunctionSelector.decode/1`	one item per call — no whole-ABI human-readable list
`iface.encodeFunctionData(fn, args)`	`encodeFunctionData`	`ABI.encode_call/3`, e.g. `ABI.encode_call("transfer(address,uint256)", [to, amount])`	positional arg list; the address arg is 20 bytes
`iface.decodeFunctionData(data)`	`decodeFunctionData`	`ABI.decode_call/3`	—
`iface.decodeFunctionResult(fn, data)`	`decodeFunctionResult`	`ABI.decode("(uint256)", return_data)`	pass the return tuple type, not the function signature
`AbiCoder.encode(types, values)`	`encodeAbiParameters`	`ABI.encode("(uint256,address)", [{n, addr}])`	tuple type string, values as one tuple; no selector
`iface.getFunction(fn).selector`	`toFunctionSelector`	`ABI.method_id/1`	4 raw bytes
`iface.parseError(data)`	`decodeErrorResult`	`ABI.decode_error/3`, or `errors:` on `call_trx/2` / `execute_trx/3`	—
`solidityPacked(types, values)`	`encodePacked`	`ABI.encode_packed/2`	—
`new Contract(addr, abi, runner)`	`getContract`	none — inline `{"sig(types)", args}` calldata, or a module generated by `mix cartouche.gen` (`call_<fn>`, `execute_<fn>`, `prepare_<fn>`, `decode_event/2`)	no contract object; the generated module is the closest thing and is compile-time, not runtime
`contract.fn.staticCall(args)`	`readContract`	`Cartouche.RPC.call_trx(%Cartouche.Transaction.Call{destination: addr, data: calldata})` then `ABI.decode/3`	two steps unless you use generated bindings
`contract.fn(args)`	`writeContract`	`Cartouche.RPC.execute_trx(addr, {"fn(types)", args}, opts)`	see Transactions — simulates first by default
—	`simulateContract`	`execute_trx/3` with `verify: true` (default), or `call_trx/2` with `from:`	simulation is on by default — the opposite of ethers, which never simulates
—	`erc20Abi`	`Cartouche.Erc20.Call.balance_of/3` (read), `Cartouche.Erc20.transfer/4` (send)	—

Events and filters

ethers v6	viem	Cartouche	Difference
`contract.on(event, cb)`	`watchContractEvent` / `watchEvent`	`Cartouche.Filter.start_link(kind: :log, address: addr, topics: [...], events: [...])` + `Cartouche.Filter.listen/1`	a supervised GenServer polling `eth_getFilterChanges` every `check_delay` ms (default 3000); delivers `%Cartouche.Filter.Log{}` messages to the listening pid — no callback
`provider.on("block", cb)`	`watchBlocks`	`Cartouche.Filter.start_link(kind: :block)`	delivers `{:hashes, [hash]}`
`provider.on("pending", cb)`	`watchPendingTransactions`	`Cartouche.Filter.start_link(kind: :pending)`	same shape
`iface.encodeFilterTopics`	`encodeEventTopics`	`ABI.Event.encode_event_topics/2`	—
`iface.parseLog(log)`	`decodeEventLog`	`ABI.Event.decode_event/4`	—
`eth_newBlockFilter` & co.	`createBlockFilter` & co.	`Cartouche.RPC.new_block_filter/1`, `new_pending_transaction_filter/1`, `get_filter_logs/2`	—

Node-managed accounts

The ethers JsonRpcSigner / viem "JSON-RPC account" path — the node holds the key and signs.

ethers v6	viem	Cartouche	Difference
`provider.getSigner().sendTransaction(tx)`	`sendTransaction` with a JSON-RPC account	`Cartouche.RPC.send_transaction/2`	`eth_sendTransaction` — the node signs
`provider.listAccounts()`	`getAddresses`	`Cartouche.RPC.accounts/1`	—
`eth_sign` via node	—	`Cartouche.RPC.sign/3`	distinct from `Cartouche.Signer.sign/3`; this is the node's key
`eth_signTransaction`	—	`Cartouche.RPC.sign_transaction/2`, `fill_transaction/2`	—

Chains

ethers v6	viem	Cartouche	Difference
`Network.from("sepolia")`	`sepolia` chain object	`Cartouche.Chain.parse_id(:sepolia)` → `11155111`	an atom → id map only; no currency, RPC URLs, explorers or contract addresses (roadmap task 9013)

Cartouche extras with no ethers/viem counterpart

Cartouche.OpenChain.lookup/3 (selector → signature lookup), Cartouche.Sleuth (bytecode queries), Cartouche.VM (in-process EVM subset for pure functions), Cartouche.RPC.eth_config/1 and eth_capabilities/1, the Cloud KMS backends, and the whole Cartouche.Solana.* tree.

Not in Cartouche — and where it is instead

ethers / viem	Where
ENS (`resolveName`, `lookupAddress`, `namehash`)	`onchain` — `Onchain.ENS`
Multicall (`multicall`)	`onchain` — `Onchain.Multicall`
`HDNodeWallet`, `Mnemonic`, keystore JSON	roadmap task 9015
`waitForTransactionReceipt`, a client struct	roadmap task 9017 (`onchain`)
`FallbackProvider` / `fallback` transport	roadmap task 9014
chain objects	roadmap task 9013
test client (`setBalance`, `impersonateAccount`, `mine`, `snapshot`)	roadmap task 9016
SIWE (`siwe`)	roadmap task 9018 (`onchain`)
`getLogs`, `getTransaction`, `getStorage`	roadmap tasks 2128, 2129, 2130 (bundle `cartouche_rpc_read_surface`, behind the 2137 transport move)
`formatUnits`, `getCreate2Address`, checksum validation	no wrapper and no task today — a few lines of Elixir

← Previous Page Changelog