@waxseal/verify

Verify Wax Seal Ed25519 identities locally and on-chain.

• Zero dependencies — uses the built-in WebCrypto API.
• Universal — works in Node.js 18+ and all modern browsers.
• Dual package — ships both ESM and CommonJS builds with full TypeScript types.

A Wax Seal is a generative wax-seal NFT bound to a single Ed25519 keypair. This library lets any app confirm that:

1. A signature was produced by the key behind a given fingerprint (offline, no network), and
2. That fingerprint is minted on-chain as a Wax Seal identity.

Install

npm install @waxseal/verify
# or: pnpm add @waxseal/verify / yarn add @waxseal/verify

Quick start

import { verifySeal } from '@waxseal/verify';

const result = await verifySeal({
  fingerprint: 'a1b2c3d4...',              // 64-char hex = SHA-256(public key DER)
  publicKeyPem: '-----BEGIN PUBLIC KEY-----\n...',
  message: 'I authored this post.',
  signature: 'base64url-encoded-ed25519-sig',
});

if (result.valid && result.onChain) {
  console.log('Verified:', result.displayName, 'on', result.chain?.name);
}

Omit message / signature to do an on-chain-only lookup (just confirm the fingerprint is a minted identity):

const result = await verifySeal({ fingerprint: 'a1b2c3d4...' });
// result.onChain → true | false

API

verifySeal(params): Promise<VerifyResult>

Full verification. Verifies the Ed25519 signature locally (if publicKeyPem + message + signature are supplied) and checks the fingerprint on-chain.

| Param | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------ | | fingerprint | string | yes | 64-char hex (SHA-256 of the Ed25519 public key DER). 0x optional.| | publicKeyPem | string | no | PEM-encoded Ed25519 public key. Required for signature checks. | | message | string | no | The signed message. Required for signature checks. | | signature | string | no | Base64url-encoded Ed25519 signature. | | chain | string | no | Preferred chain key (e.g. "base", "bsc") to speed up lookup. | | apiBase | string | no | Override API base URL. Defaults to https://api.waxseal.id. |

VerifyResult

interface VerifyResult {
  valid: boolean;              // signature valid (or on-chain existence when no sig given)
  onChain: boolean;            // fingerprint is minted on a supported chain
  fingerprint: string;         // normalized 64-char hex
  keyId: string;               // last 16 hex chars, uppercased
  displayName?: string;        // on-chain display name
  owner?: string;              // wallet that owns the NFT
  mintedAt?: number;           // unix seconds
  chain?: { name: string; chainId: number; key: string };
  publicKeyVerified?: boolean; // publicKeyPem hashes to the claimed fingerprint
  error?: string;              // human-readable failure reason
}

Other exports

• computeFingerprint(publicKeyPem) — hex(SHA-256(DER)) for a PEM key.
• verifySignatureLocal(publicKeyPem, message, signature) — offline Ed25519 check, no network.
• checkOnChain(fingerprint, { apiBase?, chain? }) — on-chain lookup only.
• createVerifier(apiBase) — bind all helpers to a custom/self-hosted API base.

REST equivalent

This package wraps a single public endpoint. You can call it directly from any stack:

POST https://api.waxseal.id/api/verify/seal
Content-Type: application/json

{ "fingerprint": "<64-char hex>", "publicKeyPem"?: "...", "message"?: "...", "signature"?: "...", "chain"?: "base" }

The response shape matches VerifyResult above.

License

MIT