@zoza/shield

Server-side wallet-security toolkit. Decode EVM calldata, score EIP-712 signature requests for drainer risk, check URLs against the phishing registry. The same engine powers the Zoza Shield browser extension — this is it as an HTTP API.

Install

npm install @zoza/shield

Who uses this

• Exchanges calling decode() before relaying user-signed transactions — reject approve UNLIMITED to unknown spenders automatically.
• Wallet providers wrapping their RPC proxy — pre-warn users on Permit2 drainer patterns before the signature prompt.
• Anti-fraud pipelines feeding every inbound eth_signTypedData_v4 through assessSignature() for domain-mismatch detection.
• Any backend that stores dApp URLs — run checkURL() on incoming referrers.

Quick start

import { ShieldClient } from '@zoza/shield';

const shield = new ShieldClient({ apiKey: process.env.ZOZA_SHIELD_KEY! });

// 1. Decode calldata before relaying
const decoded = await shield.decode({
  calldata: '0x095ea7b3000000000000000000000000...', // approve(spender, MAX_UINT256)
  chain: 'eth',
  origin: 'https://app.uniswap.org',
});
if (decoded.decoded?.risk === 'critical') {
  // reject, or require an out-of-band confirmation step
}

// 2. Score a signature request
const risk = await shield.assessSignature({
  typed_data: userSuppliedEIP712,
  origin: 'https://example.com',
});
if (risk.signature.domainOriginMismatch) {
  // the domain the signature targets doesn't match the page — almost certainly a drain
}

// 3. Check an arbitrary URL
const site = await shield.checkURL({ url: 'https://uniswap-v3-claim.xyz' });
if (site.action === 'block') return res.status(403).send(site.warning);

API

new ShieldClient({ apiKey, apiUrl?, fetch? })

| Option | Type | Notes | |---|---|---| | apiKey | string (required) | Issued at zoza.world/developers/shield. Format shd_<base64>. | | apiUrl | string | Default https://shield-api.zoza.world. | | fetch | typeof fetch | Optional — needed on Node <18 or custom request signers. |

shield.decode({ calldata, chain?, origin? })

Decodes EVM calldata. Returns { decoded, site_status, chain }.

shield.assessSignature({ typed_data, origin?, chain? })

Scores an EIP-712 signature request. Catches Permit / Permit2 / PermitForAll patterns + domain-mismatch attempts.

shield.checkURL({ url })

Public phishing-registry lookup. Returns { status, action, warning? }.

shield.getSurveillanceRegistry()

Public: the Shield v3 covert-data-collection vendor list.

shield.getKeyInfo()

Your plan, daily quota, and usage today.

Chain support

EVM: Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Avalanche, Fantom. Solana + Tron + Bitcoin are handled by the browser extension's in-wallet hooks; the HTTP API is calldata-decoder only.

Tests

npm install
npm test

Mocked-fetch unit tests. No live network needed.

License

MIT © Zoza