Skip to main content

Ledger signing

The dchain CLI can sign transactions with a Ledger hardware device using either of dchain's two account key algorithms. Each algorithm talks to a different Ledger application, derives addresses over a different coin type, and produces a different signature preimage. This page covers key registration, signing SDK transactions, signing raw EVM transactions, and the limitations that apply to Ledger signing on dchain.

Overview​

Key typeLedger appCoin typeSign preimageAddress form
secp256k1Cosmos app118'sha256 over amino JSONstandard Cosmos account
eth_secp256k1Ethereum app60'keccak over EIP-712 wrapkeccak (MetaMask-compatible) 20-byte address

Use the secp256k1 key type for the standard Cosmos experience. The Cosmos app clear-signs the transaction JSON on the device screen, so you can read and confirm every field before approving.

Use the eth_secp256k1 key type when you need MetaMask-compatible keccak addresses — for example when the same account must line up with an EVM address — or when you need to sign raw EVM transactions offline with dchain tx evm-sign. The trade-off is that the Ethereum app does not clear-sign the amino JSON; it shows two typed-data hashes instead (see Signing SDK transactions).

Key registration​

dchain's default --key-type is eth_secp256k1 (overridden from the SDK default in cmd/dchain/cmd/commands.go), so dchain keys add <name> --ledger without an explicit --key-type targets the Ethereum app. To register via the Cosmos app you must pass --key-type secp256k1 explicitly — otherwise registration fails with failed to generate ledger key while the Cosmos app is open.

secp256k1 (Cosmos app)​

dchain keys add <name> --ledger --key-type secp256k1

Open the Cosmos app on the device first. The CLI forces coin type 118' for a Ledger secp256k1 key unless you pass an explicit --coin-type. The device clear-signs the address derivation and you confirm it on screen.

eth_secp256k1 (Ethereum app)​

dchain keys add <name> --ledger --key-type eth_secp256k1

Open the Ethereum app on the device first. The key is derived over the m/44'/60'/0'/0/0 path. The device shows the hex Ethereum address for confirmation; the CLI stores the same 20 bytes under dchain's bech32 prefix, so the key is listed as dchain1… with an eth_secp256k1 public key.

Coin types​

Key / registration pathCoin type
Software key (dchain default)60
Ledger secp256k1 (Cosmos app)118'
Ledger eth_secp256k1 (Ethereum app)60'
Software keys on dchain default to coin type 60 (app/params/config.go). A Ledger secp256k1 key

derives over coin type 118'. This means the same mnemonic produces different addresses depending on where it is used: a software key and a Ledger secp256k1 key from the same seed will not share an address. The Ledger eth_secp256k1 key (coin type 60') matches the software default coin type, but still differs by key algorithm and address hashing. Always confirm the derived address before funding an account. :::

Signing SDK transactions​

Both Ledger paths sign in SIGN_MODE_LEGACY_AMINO_JSON. Ledger signing forces amino JSON — SIGN_MODE_TEXTUAL is rejected on the device path.

Cosmos app (secp256k1). The device clear-signs the amino JSON. You can read and confirm every field of the transaction on the device screen before approving. The signature is a sha256 over the amino sign bytes.

Ethereum app (eth_secp256k1). The CLI wraps the amino sign document in an EIP-712 typed-data structure and the device signs the keccak of that structure. The device cannot clear-sign the fields; it shows only the two typed-data hashes (the EIP-712 Domain and Message hashes) — this is a semi-blind signature. To let you verify them, the CLI prints both hashes to stderr before touching the device:

Verify EIP-712 on Ledger (EVM chain ID 430):
Domain: <32-byte hash>
Message: <32-byte hash>

Compare the device's two hashes against these before approving. The Ethereum app requires blind signing to be enabled (Ethereum app → Settings → Blind signing) before it will sign hashed EIP-712 payloads; without it the device rejects the request with APDU_CODE_BAD_KEY_HANDLE.

The EVM chain ID used to build the EIP-712 domain is taken from --evm-chain-id or, if that flag is not set, from [evm].evm-chain-id in app.toml (currently 430 on dchain dev/testnets). It is not derived from the Cosmos --chain-id; a Cosmos chain ID is not an EIP-155 chain ID. If the configured EVM chain ID is 0, EIP-712 signing fails with a clear error.

Signing raw EVM transactions​

dchain tx evm-sign unsigned.json --from <eth-key>

evm-sign signs a raw EVM transaction with an eth_secp256k1 Ledger key. It is offline only: there is no RPC or broadcast path. It reads geth-style transaction JSON that carries an explicit hex chainId and zero v/r/s, signs it on the Ethereum app, and prints the signed transaction JSON plus the raw transaction bytes. Submit the raw bytes later via eth_sendRawTransaction.

Constraints:

  • --from must name a stored eth_secp256k1 Ledger key. Cosmos keys use the SDK tx commands instead.
  • Only legacy (0x0) and EIP-1559 (0x2) transactions are supported.
  • The input must be unsigned: v, r, and s must all be zero.
  • If --evm-chain-id/app.toml is set, the transaction's chainId must match it.
  • --output-document <file> writes the result to a file with mode 0600 instead of stdout.

Example​

A minimal EIP-1559 transfer of 1 dt (0xde0b6b3a7640000 wei) on EVM chain ID 430 (0x1ae), gas limit 21000:

{
"type": "0x2",
"chainId": "0x1ae",
"nonce": "0x0",
"to": "0x1111111111111111111111111111111111111111",
"value": "0xde0b6b3a7640000",
"gas": "0x5208",
"maxPriorityFeePerGas": "0x3b9aca00",
"maxFeePerGas": "0x2e90edd000",
"input": "0x",
"accessList": [],
"v": "0x0",
"r": "0x0",
"s": "0x0"
}

geth's strict JSON decoder requires input and the zero v/r/s fields to be present (missing required field 'input' in transaction otherwise); evm-sign then verifies they are zero. Note the fee cap: dchain networks run a feemarket floor (125 gwei on current networks), so maxFeePerGas must clear it or the transaction is rejected from the mempool.

Sign it, then broadcast the raw bytes via JSON-RPC:

dchain tx evm-sign unsigned.json --from myeth --output-document signed.json

# Extract the raw_transaction field and submit it:
curl -s -X POST http://localhost:8545 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_sendRawTransaction","params":["<raw_transaction>"]}'

Limitations​

Extension options — unavailable with Ledger, regardless of key type​

Both Ledger paths sign amino JSON, and the SDK's amino-JSON sign handler refuses any transaction carrying TxBody extension options. Transactions needing extension options must use a software key (default SIGN_MODE_DIRECT, which covers them fully).

Credential-gated messages cannot be Ledger-signed​

dchain carries Verifiable Presentations as a TxBody extension option (--verifiable-presentation), so every VP-gated message — dgov vote, notarise, create-validator, register-notary — inherits the limitation above, with either key type. The workaround is to use a software key.

Signing-setup matrix​

Signing setupSign modeWhat the chain verifies--unorderedExtension options
Software key, either algo (default)DIRECTsignature over the full protobuf sign doc✅ supported — unordered/timeout_timestamp are inside the signed bytes✅ works, fully signed
Software eth_secp256k1, forced --sign-mode amino-jsonAMINOraw keccak over the full amino sign bytes (never reaches EIP-712)✅ supported — fields are in the signed bytes❌ SDK refuses to produce amino sign bytes
Ledger secp256k1 (Cosmos app)AMINOsha256 over the full amino sign bytes (no EIP-712 anywhere)✅ supported — current Cosmos app versions sign the extra root keys, and the signature covers them (verified on a local node)❌ same SDK refusal
Ledger eth_secp256k1 (Ethereum app)AMINO wrapped in EIP-712EIP-712 typed-data hash over the amino sign doc❌ rejected — the CLI refuses with a clear error before signing, and nodes fail verification closed❌ same SDK refusal

Every ❌ in the matrix is an outright refusal, never a silent signature with reduced coverage — the impact is on availability only, not security. The EIP-712 schema's exclusion of the unordered fields does not create replay risk: both signer and verifier fail closed. The same rejection applies to --fee-granter/--fee-payer on the Ledger eth_secp256k1 path. On the Cosmos-app path, unordered transactions are fully signature-covered (the sha256 preimage is the complete amino sign doc, unordered/timeout_timestamp included), so replay protection is intact; very old Cosmos app versions with a strict root-key whitelist may still reject the unfamiliar fields on-device.

Custom-module messages​

Custom-module messages (notary, vcv, depository, dgov) lack legacy-amino registrations and therefore cannot be signed via the eth_secp256k1 Ledger path — you get a clear error at signing time. SDK-module messages (bank, staking, gov) work.

One connected Ledger​

The Ethereum app path requires exactly one connected Ledger device.