@cosmjs/proto-signing

Protobuf-based transaction signing for Cosmos SDK 0.40+

Provides Protobuf Direct signing mode for modern Cosmos SDK chains. This is the preferred signing method for new applications.

npm install @cosmjs/proto-signing

DirectSecp256k1HdWallet

HD wallet using BIP-39 mnemonic with Protobuf Direct signing. Implements OfflineDirectSigner.

Static Methods

Method	Parameters	Returns
generate	length?: 12 | 15 | 18 | 21 | 24, options?: Partial<DirectSecp256k1HdWalletOptions>	Promise<DirectSecp256k1HdWallet>
fromMnemonic	mnemonic: string, options?: Partial<DirectSecp256k1HdWalletOptions>	Promise<DirectSecp256k1HdWallet>
deserialize	serialization: string, password: string	Promise<DirectSecp256k1HdWallet>
deserializeWithEncryptionKey	serialization: string, encryptionKey: Uint8Array	Promise<DirectSecp256k1HdWallet>

Instance Methods

Method	Parameters	Returns
getAccounts	—	Promise<readonly AccountData[]>
signDirect	signerAddress: string, signDoc: SignDoc	Promise<DirectSignResponse>
serialize	password: string	Promise<string>
serializeWithEncryptionKey	encryptionKey: Uint8Array, kdfConfiguration: KdfConfiguration	Promise<string>

Instance Properties

Property	Type
mnemonic	string

Options

interface DirectSecp256k1HdWalletOptions {
  readonly bip39Password: string;   // default: ""
  readonly hdPaths: readonly HdPath[]; // default: [makeCosmoshubPath(0)]
  readonly prefix: string;          // default: "cosmos"
}

Usage

import { DirectSecp256k1HdWallet, makeCosmoshubPath } from "@cosmjs/proto-signing";

const wallet = await DirectSecp256k1HdWallet.generate(24, { prefix: "cosmos" });
const [{ address, pubkey }] = await wallet.getAccounts();

const restored = await DirectSecp256k1HdWallet.fromMnemonic(wallet.mnemonic, {
  prefix: "osmo",
  hdPaths: [makeCosmoshubPath(0), makeCosmoshubPath(1)],
});

DirectSecp256k1Wallet

Single-key wallet for Protobuf Direct signing. Implements OfflineDirectSigner.

Method	Parameters	Returns
fromKey (static)	privkey: Uint8Array, prefix?: string	Promise<DirectSecp256k1Wallet>
getAccounts	—	Promise<readonly AccountData[]>
signDirect	address: string, signDoc: SignDoc	Promise<DirectSignResponse>

DirectEthSecp256k1HdWallet

HD wallet using Ethereum’s secp256k1 curve for chains with EVM compatibility. Supports generate, fromMnemonic, getAccounts, and signDirect like DirectSecp256k1HdWallet, but uses the Ethereum HD path m/44'/60'/0'/0/0 by default and Keccak-256 for address derivation. Does not support wallet serialization (serialize/deserialize).

DirectEthSecp256k1Wallet

Single-key wallet using Ethereum’s secp256k1 curve. Supports fromKey, getAccounts, and signDirect like DirectSecp256k1Wallet, but reports algo: "eth_secp256k1" and uses Keccak-256 for signing.

Registry

Maps type URLs to protobuf codec implementations for encoding and decoding messages.

Method	Parameters	Returns
constructor	customTypes?: Iterable<[string, GeneratedType]>	Registry
register	typeUrl: string, type: GeneratedType	void
lookupType	typeUrl: string	GeneratedType | undefined
encode	encodeObject: EncodeObject	Uint8Array
encodeAsAny	encodeObject: EncodeObject	Any
encodeTxBody	txBodyFields: TxBodyValue	Uint8Array
decode	decodeObject: DecodeObject	any
decodeTxBody	txBody: Uint8Array	TxBody

Usage

import { Registry } from "@cosmjs/proto-signing";
import { defaultRegistryTypes } from "@cosmjs/stargate";
import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx";

const registry = new Registry(defaultRegistryTypes);
registry.register("/my.custom.MsgCustom", MsgCustom);

const encoded = registry.encode({
  typeUrl: "/cosmos.bank.v1beta1.MsgSend",
  value: MsgSend.fromPartial({
    fromAddress: "cosmos1sender...",
    toAddress: "cosmos1recipient...",
    amount: [{ denom: "uatom", amount: "1000" }],
  }),
});

Key Types

EncodeObject

interface EncodeObject {
  readonly typeUrl: string;
  readonly value: any;
}

DecodeObject

interface DecodeObject {
  readonly typeUrl: string;
  readonly value: Uint8Array;
}

TxBodyEncodeObject

interface TxBodyEncodeObject extends EncodeObject {
  readonly typeUrl: "/cosmos.tx.v1beta1.TxBody";
  readonly value: TxBodyValue;
}

AccountData

interface AccountData {
  readonly address: string;
  readonly algo: Algo;
  readonly pubkey: Uint8Array;
}

OfflineDirectSigner

interface OfflineDirectSigner {
  readonly getAccounts: () => Promise<readonly AccountData[]>;
  readonly signDirect: (signerAddress: string, signDoc: SignDoc) => Promise<DirectSignResponse>;
}

OfflineSigner

type OfflineSigner = OfflineAminoSigner | OfflineDirectSigner;

DecodedTxRaw

interface DecodedTxRaw {
  readonly authInfo: AuthInfo;
  readonly body: TxBody;
  readonly signatures: readonly Uint8Array[];
}

Helper Functions

Function	Parameters	Returns
makeAuthInfoBytes	signers: ReadonlyArray<{ pubkey: Any; sequence: bigint | number }>, feeAmount: readonly Coin[], gasLimit: number, feeGranter: string | undefined, feePayer: string | undefined, signMode?: SignMode	Uint8Array
makeSignDoc	bodyBytes: Uint8Array, authInfoBytes: Uint8Array, chainId: string, accountNumber: number	SignDoc
makeSignBytes	signDoc: SignDoc	Uint8Array
decodeTxRaw	tx: Uint8Array	DecodedTxRaw
encodePubkey	pubkey: Pubkey	Any
decodePubkey	pubkey: Any	Pubkey
decodeOptionalPubkey	pubkey: Any | null | undefined	Pubkey | null
makeCosmoshubPath	account: number	HdPath
coin	amount: number | string, denom: string	Coin
coins	amount: number | string, denom: string	Coin[]
parseCoins	input: string	Coin[]
extractKdfConfiguration	serialization: string	KdfConfiguration
executeKdf	password: string, configuration: KdfConfiguration	Promise<Uint8Array>