@metalntwx/metal-ts

The TypeScript SDK for the Metal chain. Build, sign, and broadcast MIP20 gas transactions — the 0x7f envelope that lets an account pay gas in a stablecoin instead of native ETH.

The transaction codec is the canonical Rust implementation that chain validators run, compiled to WASM — so there is no Rust↔JS drift to manage. On top of the codec, the SDK ships a viem integration for the common wallet and signer flows.

Install

npm install @metalntwx/metal-ts viem

viem is an optional peer dependency. Install it for the wallet helpers (writeMip20Contract, sendMip20Call); skip it if you only need the codec (see Without viem).

Call initMetalCodec() once before any other function — it loads the WASM module and is safe to call repeatedly (subsequent calls reuse the instance).

Send a transfer

Works with any EIP-1193 wallet viem supports — MetaMask, Rabby, Frame, hardware wallets — and with a local private key.

import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { writeMip20Contract } from "@metalntwx/metal-ts";

const rpc = "https://devnet.n4.xyz/rpc-v0";
const publicClient = createPublicClient({ transport: http(rpc) });
const walletClient = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  transport: http(rpc),
});

const erc20Abi = [
  {
    name: "transfer",
    type: "function",
    inputs: [
      { name: "to", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ type: "bool" }],
    stateMutability: "nonpayable",
  },
] as const;

const hash = await writeMip20Contract({
  walletClient,
  publicClient,
  abi: erc20Abi,
  address: usdToken,
  functionName: "transfer",
  args: [recipient, parseUnits("10", 18)],
  gasToken: usdToken, // pay gas in the same token being transferred
  gasFallback: 200_000n,
});

In the browser, pass a walletClient created from the injected provider (custom(window.ethereum)); the wallet signs the EIP-712 typed data and the SDK broadcasts the 0x7f envelope. In a Node script, use a privateKeyToAccount wallet client as above — the same call covers both.

gasToken is the MIP20 token that pays for gas. gasFallback is the gas limit used when live estimation fails (the SDK estimates automatically with headroom and falls back to this floor).

Use sendMip20Call instead of writeMip20Contract when you already have ABI-encoded calldata:

import { sendMip20Call } from "@metalntwx/metal-ts";

const hash = await sendMip20Call({
  walletClient,
  publicClient,
  to: contractAddress,
  data, // 0x-prefixed calldata
  gasToken: usdToken,
  gasFallback: 200_000n,
});

Both return the transaction hash immediately after broadcast. Await publicClient.waitForTransactionReceipt({ hash }) when you need confirmation.

Without viem

The codec and EIP-712 helpers are available from the @metalntwx/metal-ts/codec subpath, which imports nothing outside this package — use it for indexers, edge runtimes, or signing with a non-viem library such as ethers.

import {
  initMetalCodec,
  buildMip20TypedDataMessage,
  encodeSignedEnvelope,
  type Mip20Tx,
} from "@metalntwx/metal-ts/codec";

await initMetalCodec();

const tx: Mip20Tx = {
  chainId: 1337n,
  nonce: 0n,
  maxPriorityFeePerGas: 1n,
  maxFeePerGas: 1n,
  gasLimit: 200_000n,
  to: recipient,
  data: "0x",
  gasToken: usdToken,
};

// Hand the typed data to any EIP-712 signer, then wrap the signature.
const typedData = buildMip20TypedDataMessage(tx, BigInt(tx.chainId));
const sig = await signTypedDataWithYourSigner(typedData); // 65 bytes: r‖s‖v
const raw = encodeSignedEnvelope(tx, sig);
await provider.send("eth_sendRawTransaction", [toHex(raw)]);

authorizationListHash, value: 0, and the MIP20Tx typehash are computed by the WASM codec so the digest a wallet signs always matches what the chain expects. Never hand-roll the typed-data message.

Exports

| Import from | Contents | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | @metalntwx/metal-ts | Everything below, plus the viem helpers sendMip20Call, writeMip20Contract, signatureBytes, estimateGasLimit. | | @metalntwx/metal-ts/codec | initMetalCodec, buildMip20TypedDataMessage, encodeSignedEnvelope, signingHash, authorizationSigningHash, mip20AuthorizationListHash, txTypeByte, factoryAddress, MIP20_TX_TYPES, and the Mip20Tx / Mip20Authorization / Mip20TypedData types. No viem. |

Building from source

The WASM codec and its TypeScript bindings are generated from the canonical Rust crate at cryptography/metal-mip20-codec:

pnpm build   # runs the WASM build + ts-rs binding generation

Both artifacts (wasm/, src/generated/) are gitignored and rebuilt on prepack.