x402z-shared

Shared utilities for the erc7984-mind-v1 x402 scheme.

Install

pnpm add x402z-shared

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 (Node)

import {
  createRelayer,
  createEncryptedAmountInput,
  SepoliaConfig,
} from "x402z-shared";

Unwrap helpers (Node)

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

Wrap helpers (Node)

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

Token helper (Node)

import { ConfidentialToken } from "x402z-shared";

const token = new ConfidentialToken({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  relayer,
  signer: { address, signTypedData, writeContract },
});
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 (Node)

import { getTransferAmounts } from "x402z-shared";

const transfers = await getTransferAmounts({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  txHash: "0xTransactionHash",
  from: "0xSender",
  to: "0xReceiver",
  relayer,
  signer: { address, signTypedData },
});
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 (Node)

import { ConfidentialToken } from "x402z-shared";

const token = new ConfidentialToken({
  rpcUrl: "https://sepolia.infura.io/v3/...",
  tokenAddress: "0xToken",
  relayer,
  signer: { address, signTypedData, writeContract },
});
const txHash = await token.setObserver("0xHolder", "0xObserver");
console.log(txHash);

Notes

• Scheme name: erc7984-mind-v1
• For browser usage, use x402z-shared-web.

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.
• createRelayer: creates a Zama relayer instance (node).
• createEncryptedAmountInput: builds encrypted handle + proof for amounts.
• 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.
• 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.
• re-exported types from @x402/core/types: shared x402 types.