x402z-shared-web

Browser relayer + token helpers for the erc7984-mind-v1 x402 scheme.

Install

pnpm add x402z-shared-web

Folder map

• src/core/: ABI, constants, types, utils
• src/relayer/: relayer helpers
• src/token/: token, balance, observer, transfer helpers
• src/index.ts: public exports

Relayer helpers (Browser)

import {
  createRelayer,
  getBrowserEthereumProvider,
  createEncryptedAmountInput,
  getSepoliaConfig,
} from "x402z-shared-web";
import type { FhevmInstanceConfig } from "x402z-shared-web";

const provider = getBrowserEthereumProvider();
const relayerConfig: FhevmInstanceConfig = {
  ...(getSepoliaConfig() as object),
  network: provider,
};
const relayer = await createRelayer(relayerConfig);
const encrypted = await createEncryptedAmountInput(
  relayer,
  "0xToken",
  "0xBatcher",
  1000,
);

createRelayer calls initSDK() for you the first time.

Unwrap helpers (Browser)

import {
  getTokenEip712Domain,
  prepareUnwrapAuthorization,
  getUnwrapHandleFromLogs,
} from "x402z-shared-web";

Wrap helpers (Browser)

import { ensureUnderlyingAllowance, getUnderlyingTokenAddress } from "x402z-shared-web";

Token helper (Browser)

import { ConfidentialToken } from "x402z-shared-web";
import { createWalletClient, custom } from "viem";
import { createBrowserSigner, getBrowserEthereumProvider } from "x402z-shared-web";

const provider = getBrowserEthereumProvider();
const signer = await createBrowserSigner(provider);
const walletClient = createWalletClient({
  transport: custom(provider as any),
  account: signer.address,
});
const token = new ConfidentialToken({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  relayer,
  walletClient,
  signer,
});
const balance = await token.balanceOf("0xWallet");
console.log(balance.toString());

Notes:

• Balance decryption is allowed for the account or its observer (ERC7984ObserverAccess).
• Unauthorized observer errors throw confidentialErrorCodes.observerNotAuthorized (ConfidentialErrorCode).

Transfer amount helper (Browser)

import { getTransferAmounts } from "x402z-shared-web";
import { createBrowserSigner, getBrowserEthereumProvider } from "x402z-shared-web";

const provider = getBrowserEthereumProvider();
const signer = await createBrowserSigner(provider);
const transfers = await getTransferAmounts({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  txHash: "0xTransactionHash",
  relayer,
  signer,
});
console.log(transfers[0]?.amount?.toString());

Notes:

• Transfer amount decryption is allowed for holder, payee, or an observer set via ERC7984ObserverAccess.
• Unauthorized observer errors throw confidentialErrorCodes.observerNotAuthorized (ConfidentialErrorCode).

Observer helper (Browser)

import { ConfidentialToken } from "x402z-shared-web";
import { createWalletClient, custom } from "viem";
import { createBrowserSigner, getBrowserEthereumProvider } from "x402z-shared-web";

const provider = getBrowserEthereumProvider();
const signer = await createBrowserSigner(provider);
const walletClient = createWalletClient({ transport: custom(provider as any) });
const token = new ConfidentialToken({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  relayer,
  walletClient,
  signer,
});
const txHash = await token.setObserver("0xHolder", "0xObserver");
console.log(txHash);

Notes

• Web builds use @zama-fhe/relayer-sdk/web (no CDN script tag or bundle).
• Requires an injected wallet for signing (e.g. MetaMask).
• Scheme name: erc7984-mind-v1

API surface

Exports:

• confidentialTokenAbi: FHEToken ABI fragment used by helpers.
• confidentialPaymentTypes: EIP-712 type definitions for confidential payments.
• confidentialErrorCodes: mapped error codes for relayer/decryption flows.
• createNonce: generates a random bytes32 nonce.
• hashEncryptedAmountInput: hashes an encrypted handle for authorization binding.
• normalizeAmount: coerces amounts to on-chain uint64-safe values.
• createBrowserSigner: builds a signer from an injected provider.
• getBrowserEthereumProvider: fetches the injected EIP-1193 provider.
• createRelayer: creates a Zama relayer instance (browser).
• createEncryptedAmountInput: builds encrypted handle + proof for amounts.
• getSepoliaConfig: returns default browser relayer config for Sepolia.
• initSDK: initializes the browser SDK once.
• publicDecrypt: performs public decryption with proof.
• SepoliaConfig: default relayer config for Sepolia.
• decryptEuint64: user decryption flow for a single handle.
• getTokenEip712Domain: reads token EIP-712 domain with fallbacks.
• getUnwrapHandleFromLogs: extracts unwrap handle from receipt logs.
• prepareUnwrapAuthorization: creates/ signs unwrap authorization payload.
• ensureUnderlyingAllowance: checks/approves underlying ERC-20 allowance.
• getUnderlyingTokenAddress: reads underlying ERC-20 address from FHEToken.
• getTransferAmounts: decrypts transfer amounts for a payment tx.
• ConfidentialToken: high-level token helper (balance, wrap/unwrap).

Types:

• ConfidentialErrorCode: discriminated error codes for decrypt flows.
• ConfidentialPaymentAuthorization: signed payment authorization shape.
• UnwrapAuthorization: signed unwrap authorization shape.
• ConfidentialPaymentPayload: full payment payload sent to server.
• ConfidentialRequirementsExtra: scheme requirements extension payload.
• ConfidentialPaymentInput: relayer input for confidential payments.
• BrowserEthereumProvider: EIP-1193 provider type.
• BrowserSigner: browser signer interface.
• TransferAmount: decrypted transfer amount record.
• TransferQueryOptions: query options for transfer amount lookup.
• ConfidentialTokenOptions: constructor config for ConfidentialToken.
• FhevmInstanceConfig: relayer configuration type.
• RelayerInstance: relayer instance type.
• RelayerSigner: EIP-712 signer interface for relayer ops.
• RelayerSdkModule: relayer SDK module type.
• re-exported types from @x402/core/types: shared x402 types.