Wallets

This guide covers two perspectives: connecting your dApp to the Armchain Wallet, and building custom wallet support for Armchain.

Armchain Wallet

The Armchain Wallet is the official browser extension wallet for the Armchain network. It is a fork of Wigwam wallet, customized for ML-DSA44 post-quantum cryptography.

Key Features

ML-DSA44 key management: Generates and stores post-quantum keys
HD wallet derivation: BIP-39 mnemonic with Armchain coin type (65536)
Hardened derivation only: All child keys use hardened paths for security
Type 3 transactions: Signs PQC transactions natively
EIP-1559 gas pricing: Dynamic fee support
Multi-account support: Derive multiple accounts from a single seed phrase
ARM token support: Native token balance display and transfers

Network Configuration

The wallet ships with built-in Armchain network configurations:

// Devnet
{
  chainId: 55,
  name: "Armchain Devnet",
  rpcUrls: ["https://www.armchain.org/devnet"],
  nativeCurrency: { symbol: "ARM", name: "Armchain", decimals: 18 },
}

// Local Development
{
  chainId: 55,
  name: "Armchain Local",
  rpcUrls: ["http://localhost:4000"],
  nativeCurrency: { symbol: "ARM", name: "Armchain", decimals: 18 },
}

For dApp Developers

Connecting to the Wallet

The Armchain Wallet injects a provider into the browser, similar to MetaMask:

// Check if wallet is available
if (typeof window.ethereum !== "undefined") {
  // Armchain Wallet detected
}

// Request account access
const accounts = await window.ethereum.request({
  method: "eth_requestAccounts"
});
console.log("Connected account:", accounts[0]);

Using with Armchain Ethers SDK

import { BrowserProvider, Contract } from "@armchain-ethersv6/ethers";

// Connect to injected wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

console.log("Connected:", await signer.getAddress());
console.log("Balance:", await provider.getBalance(signer.address));

// Interact with contracts
const contract = new Contract(contractAddress, abi, signer);
const tx = await contract.someFunction(arg1, arg2);
await tx.wait();

Handling Chain Switching

// Switch to Armchain devnet
try {
  await window.ethereum.request({
    method: "wallet_switchEthereumChain",
    params: [{ chainId: "0x37" }],  // 55 in hex
  });
} catch (switchError) {
  // Chain not added - request to add it
  if (switchError.code === 4902) {
    await window.ethereum.request({
      method: "wallet_addEthereumChain",
      params: [{
        chainId: "0x37",
        chainName: "Armchain Devnet",
        rpcUrls: ["https://www.armchain.org/devnet"],
        nativeCurrency: {
          name: "Armchain",
          symbol: "ARM",
          decimals: 18,
        },
        blockExplorerUrls: ["https://www.armchain.org/explorer"],
      }],
    });
  }
}

Listening for Events

// Account changed
window.ethereum.on("accountsChanged", (accounts) => {
  console.log("Account switched to:", accounts[0]);
  // Refresh account-dependent UI
});

// Chain changed
window.ethereum.on("chainChanged", (chainId) => {
  console.log("Chain switched to:", parseInt(chainId, 16));
  // Reload the page or refresh state
  window.location.reload();
});

// Disconnected
window.ethereum.on("disconnect", () => {
  console.log("Wallet disconnected");
});

Signing Messages

const signer = await provider.getSigner();

// Personal sign (EIP-191)
const message = "Sign this message to verify your identity";
const signature = await signer.signMessage(message);

// The signature is an ML-DSA44 signature (3,732 bytes)
console.log("Signature:", signature);

EIP-712 Typed Data Signing

const domain = {
  name: "My dApp",
  version: "1",
  chainId: 55,
  verifyingContract: "0xCONTRACT_ADDRESS",
};

const types = {
  Order: [
    { name: "maker", type: "address" },
    { name: "amount", type: "uint256" },
    { name: "nonce", type: "uint256" },
  ],
};

const value = {
  maker: await signer.getAddress(),
  amount: parseEther("100"),
  nonce: 1,
};

const signature = await signer.signTypedData(domain, types, value);

For Wallet Developers

If you're building a wallet that supports Armchain, here are the key requirements. The recommended approach is to use the @armchain-ethersv6/ethers SDK, which handles all cryptographic operations internally.

Key Generation

Armchain uses ML-DSA44 (NIST FIPS 204) for all key operations. Key pairs are generated from a 32-byte random seed.

Component

Size

Private Key

2,560 bytes

Public Key

1,312 bytes

The SDK's Wallet.createRandom() and HDNodeWallet.fromPhrase() handle key generation automatically. If implementing from scratch, use a FIPS 204-compliant ML-DSA44 library.

HD Wallet Derivation

Armchain uses a BIP-44 compatible derivation path with all hardened indices:

m/44'/65536'/account'/0/address'

Critical: Non-hardened derivation is NOT supported with ML-DSA44. All path components must use hardened derivation.

Since ML-DSA44 key generation takes a 32-byte seed (unlike ECDSA's scalar), the HD derivation chain produces child seeds rather than child keys directly. See the @armchain-ethersv6/ethers SDK source for the reference implementation.

// Derive accounts using the SDK
import { HDNodeWallet } from "@armchain-ethersv6/ethers";

const wallet = HDNodeWallet.fromPhrase(mnemonic);
const child = wallet.derivePath("m/44'/65536'/0'/0/0'");
console.log("Address:", child.address);

Transaction Signing

All Armchain transactions must be Type 3 (PQC). The SDK handles transaction construction and signing:

import { Wallet, JsonRpcProvider } from "@armchain-ethersv6/ethers";

const provider = new JsonRpcProvider("https://www.armchain.org/devnet");
const wallet = new Wallet(privateKey, provider);

// The SDK automatically creates Type 3 transactions and signs with ML-DSA44
const tx = await wallet.sendTransaction({
  to: recipient,
  value: amount,
  // type: 3 is auto-set
});

For custom implementations, the signing process involves computing a transaction hash and producing an ML-DSA44 signature blob that includes both the raw signature and the public key (since ML-DSA44 does not support public key recovery). Refer to the Transaction Types page for the wire format specification.

Address Computation

Armchain addresses are derived from ML-DSA44 public keys using keccak256, producing standard 20-byte Ethereum-format addresses. The SDK handles this automatically via SigningKey.computeAddress().

Key Storage Considerations

ML-DSA44 private keys are 2,560 bytes (vs 32 bytes for ECDSA). This affects:

Aspect

ECDSA

ML-DSA44

Impact

Private key storage

32 bytes

2,560 bytes

~80× more storage

Key encryption time

Fast

Slightly slower

Negligible

Key backup size

Small

Larger

QR codes may not work for raw keys

Mnemonic backup

12/24 words

Same: mnemonic derives the key

Recommendation: Always support mnemonic-based backup. The 12/24 word seed phrase is the same size regardless of the underlying key type.

Common Integration Patterns

Connect Wallet Button

async function connectWallet() {
  if (!window.ethereum) {
    alert("Please install Armchain Wallet");
    return;
  }

  try {
    const accounts = await window.ethereum.request({
      method: "eth_requestAccounts"
    });
    
    const chainId = await window.ethereum.request({
      method: "eth_chainId"
    });

    if (parseInt(chainId, 16) !== 55) {
      // Not on Armchain - request switch
      await switchToArmchain();
    }

    return accounts[0];
  } catch (error) {
    console.error("Connection failed:", error);
  }
}

Transaction Helper

import { BrowserProvider, parseEther } from "@armchain-ethersv6/ethers";

async function sendARM(to: string, amount: string) {
  const provider = new BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();

  const tx = await signer.sendTransaction({
    to,
    value: parseEther(amount),
  });

  // Instant finality means one confirmation is enough
  const receipt = await tx.wait();
  return receipt;
}