x402z-shared

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

Install

``bash
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)

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

`

Unwrap helpers (Node)

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

Wrap helpers (Node)

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

Token helper (Node)

`ts
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)

`ts
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)

`ts
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.