@provenonce/sdk 0.12.0 → 0.17.0

package/README.md

@@ -25,13 +25,13 @@ console.log(creds.hash);    // unique agent identity
 console.log(creds.api_key); // use this for BeatAgent
 console.log(creds.secret);  // save — shown only once
 
-// Solana self-custody wallet (opt-in)
+// Operator wallet registration (Solana — bring your own wallet)
 const withWallet = await register('my-org', {
   registryUrl: 'https://provenonce.io',
-  walletModel: 'self-custody',
+  walletModel: 'operator',
+  walletAddress: '<your-solana-address>',
+  walletSignFn: (msg) => signWithYourWallet(msg),
 });
-// withWallet.wallet.address = Solana address
-// withWallet.wallet.secret_key = SAVE — cannot be recovered
 
 // Child registration (requires parent credentials)
 const child = await register('worker-1', {
@@ -63,7 +63,7 @@ const sigil = await agent.purchaseSigil({
 });
 
 // Start heartbeating (paid liveness proofs)
-agent.startHeartbeat();
+agent.startHeartbeat(async () => 'your-solana-tx-signature');
 
 // Get your Passport (latest lineage proof)
 const passport = await agent.getPassport();
@@ -71,7 +71,7 @@ console.log(passport?.identity_class);     // 'autonomous'
 console.log(passport?.provenonce_signature); // Ed25519 signed
 
 // Verify any proof offline — no API call needed
-const valid = BeatAgent.verifyProofLocally(passport, authorityPubKeyHex);
+const valid = BeatAgent.verifyPassportLocally(passport, authorityPubKeyHex);
 
 agent.stopHeartbeat();
 ```
@@ -85,15 +85,16 @@ agent.stopHeartbeat();
 | `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
 | `purchaseSigil(opts)` | Purchase a SIGIL identity (required for heartbeating) |
 | `updateMetadata(fields)` | Update mutable SIGIL metadata fields |
-| `heartbeat(paymentTx?, globalAnchor?)` | Submit a paid heartbeat and receive a signed lineage proof |
-| `startHeartbeat()` | Start autonomous heartbeat loop |
+| `heartbeat(paymentTx, globalAnchor?)` | Submit a paid heartbeat and receive a signed passport |
+| `startHeartbeat(paymentTxFn)` | Start autonomous heartbeat loop |
 | `stopHeartbeat()` | Stop heartbeat |
-| `getPassport()` | Get latest lineage proof (Passport) |
-| `reissueProof(paymentTx?)` | Reissue proof without extending lineage |
+| `getPassport()` | Get latest passport (cached, no network call) |
+| `getLatestPassport()` | Get latest passport (alias for getPassport) |
+| `reissuePassport(paymentTx?)` | Reissue passport without extending lineage |
 | `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
 | `getStatus()` | Get full beat status from registry |
 | `getLocalState()` | Get local state (no network call) |
-| `static verifyProofLocally(proof, pubKey)` | Verify a lineage proof offline |
+| `static verifyPassportLocally(proof, pubKey)` | Verify a passport offline |
 
 ### `BeatAgentConfig`
 
@@ -113,7 +114,7 @@ agent.stopHeartbeat();
 |--------|-------------|
 | `registryUrl` | Registry URL (required) |
 | `registrationSecret` | Registration gate (mainnet) |
-| `walletModel` | `'self-custody'` or `'operator'` (opt-in wallet) |
+| `walletModel` | `'operator'` (opt-in BYO wallet) |
 | `walletChain` | `'solana'` or `'ethereum'` |
 | `walletAddress` | Ethereum BYO address |
 | `walletSignFn` | Signing function for BYO wallets |
@@ -127,9 +128,9 @@ Returns `RegistrationResult` with `hash`, `api_key`, `secret`, `wallet?`.
 ### Phase 2 Types
 
 ```typescript
-import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
+import type { Passport, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
 
-// Passport = LineageProof (type alias)
+// Passport is the primary type. LineageProof is a deprecated alias (sunset 2026-09-01).
 // Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
 //           provenonce_signature, issued_at, valid_until, etc.
 
@@ -143,7 +144,7 @@ await agent.purchaseSigil({
   identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
   principal: 'my-agent',
   tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
-  payment_tx: 'solana-tx-signature...', // or 'devnet-skip' on devnet
+  payment_tx: 'solana-tx-signature...',
   name: 'optional-display-name'
 });
 ```

package/dist/index.d.mts

@@ -15,12 +15,11 @@
  *     registryUrl: 'https://provenonce.io',
  *   });
  *
- *   await agent.init();           // Birth in Beat time
- *   await agent.pulse(50);        // Compute 50 beats
- *   await agent.checkin();        // Report to registry
+ *   await agent.init();           // Initialize agent state
+ *   await agent.heartbeat();      // Send paid heartbeat (Phase 2)
  *
- *   // Or run the autonomous heartbeat:
- *   agent.startHeartbeat();       // Computes + checks in continuously
+ *   // Or run the autonomous heartbeat loop:
+ *   agent.startHeartbeat();       // Heartbeats at regular intervals
  *   // ... do your agent work ...
  *   agent.stopHeartbeat();
  *
@@ -41,14 +40,16 @@ type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
 /** Compliance regime */
 type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
 /**
- * Ed25519-signed lineage proof — portable, offline-verifiable credential.
- * Also known as the agent's "passport" — a cryptographic proof of identity
- * that can be verified offline without any API call or SOL cost.
+ * Ed25519-signed passport — the agent's portable, offline-verifiable credential.
+ * A cryptographic proof of identity that can be verified offline without any
+ * API call or SOL cost.
  */
-interface LineageProof {
+interface Passport {
+    format_version?: number;
     agent_hash: string;
     agent_public_key: string | null;
-    identity_class: IdentityClass;
+    authority_key_id?: string;
+    identity_class: IdentityClass | null;
     registered_at_beat: number;
     sigil_issued_at_beat: number | null;
     last_heartbeat_beat: number;
@@ -57,8 +58,38 @@ interface LineageProof {
     valid_until: number;
     provenonce_signature: string;
 }
-/** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
-type Passport = LineageProof;
+/** @deprecated Use `Passport` instead. Sunset 2026-09-01. */
+type LineageProof = Passport;
+/** W3C Verifiable Credential envelope wrapping a LineageProof */
+interface ProvenoncePassportVC {
+    '@context': [string, string];
+    type: ['VerifiableCredential', 'ProvenoncePassport'];
+    issuer: {
+        id: string;
+        authority_key_id: string;
+    };
+    issuanceDate: string;
+    expirationDate: string;
+    credentialSubject: {
+        id: string;
+        agent_hash: string;
+        agent_public_key: string | null;
+        identity_class: IdentityClass | null;
+        registered_at_beat: number;
+        sigil_issued_at_beat: number | null;
+        last_heartbeat_beat: number;
+        lineage_chain_hash: string;
+    };
+    proof: {
+        type: 'Ed25519Signature2020';
+        created: string;
+        verificationMethod: string;
+        proofPurpose: 'assertionMethod';
+        cryptosuite: 'eddsa-provenonce-2026';
+        proofValue: string;
+    };
+    format_version: number;
+}
 /** Options for purchasing a SIGIL with full namespace */
 interface SigilPurchaseOptions {
     identity_class: IdentityClass;
@@ -66,6 +97,9 @@ interface SigilPurchaseOptions {
     tier: SigilTier;
     name?: string;
     payment_tx: string;
+    at?: string;
+    skill_hash?: string;
+    ref?: string;
     substrate?: Substrate;
     substrate_provider?: SubstrateProvider;
     substrate_model?: string;
@@ -78,6 +112,14 @@ interface SigilPurchaseOptions {
     endpoint?: string;
     compliance_regime?: ComplianceRegime;
 }
+/** Result from getSigilAttribution() */
+interface SigilAttributionResult {
+    ok: boolean;
+    attribution_token?: string;
+    signup_url?: string | null;
+    already_has_sigil?: boolean;
+    error?: string;
+}
 /** Mutable SIGIL metadata fields for PATCH updates */
 interface SigilMutableFields {
     substrate?: Substrate;
@@ -106,7 +148,9 @@ interface SigilResult {
         birth_tx: string | null;
         explorer_url: string | null;
     };
-    lineage_proof?: LineageProof;
+    passport?: Passport;
+    /** @deprecated Use `passport` instead. Sunset 2026-09-01. */
+    lineage_proof?: Passport;
     fee?: {
         amount_sol: number;
         amount_lamports: number;
@@ -140,7 +184,10 @@ interface VerificationResult {
 /** Result from a paid heartbeat */
 interface HeartbeatResult {
     ok: boolean;
-    lineage_proof?: LineageProof;
+    sigil_required?: boolean;
+    passport?: Passport;
+    /** @deprecated Use `passport` instead. Sunset 2026-09-01. */
+    lineage_proof?: Passport;
     heartbeat_count_epoch?: number;
     billing_epoch?: number;
     current_beat?: number;
@@ -150,6 +197,24 @@ interface HeartbeatResult {
         tier: number;
         payment_tx: string | null;
     };
+    sponsor?: {
+        parent_hash: string;
+    };
+    error?: string;
+}
+/** RFC-021: Sponsorship record returned by the /agent/sponsor endpoint. */
+interface SponsorshipRecord {
+    parent_hash: string;
+    child_hash: string;
+    status: 'active' | 'revoked' | 'expired';
+    max_heartbeats_epoch: number;
+    heartbeats_used_epoch: number;
+    expires_at: string | null;
+    created_at?: string;
+}
+interface SponsorshipResult {
+    ok: boolean;
+    sponsorship?: SponsorshipRecord;
     error?: string;
 }
 interface Beat {
@@ -189,8 +254,34 @@ interface SpawnResult {
     ok: boolean;
     eligible: boolean;
     child_hash?: string;
+    spawn_authorization?: string;
+    receipt_based?: boolean;
+    required_beats?: number;
+    accumulated_beats?: number;
     progress_pct?: number;
     deficit?: number;
+    error?: string;
+}
+/** A signed work-proof receipt from the Beats service. */
+interface WorkProofReceipt {
+    type: string;
+    beats_verified: number;
+    difficulty: number;
+    anchor_index: number;
+    anchor_hash: string | null;
+    from_hash: string;
+    to_hash: string;
+    utc: string;
+    signature: string;
+    [key: string]: unknown;
+}
+/** Result of computeWorkProof() */
+interface WorkProofResult {
+    ok: boolean;
+    receipt?: WorkProofReceipt;
+    beats_computed?: number;
+    elapsed_ms?: number;
+    error?: string;
 }
 /** Agent status from the registry */
 interface AgentStatus {
@@ -205,21 +296,8 @@ interface AgentStatus {
     };
     difficulty?: number;
 }
-/**
- * Generate an Ed25519 keypair for agent wallet identity.
- * Returns hex-encoded raw keys (32 bytes each).
- * Uses Node.js built-in crypto — zero external dependencies.
- */
-declare function generateWalletKeypair(): {
-    publicKey: string;
-    secretKey: string;
-};
 /** Wallet info returned from root registration */
 interface WalletInfo {
-    /** Hex-encoded 32-byte Ed25519 public key (Solana self-custody only, empty otherwise) */
-    public_key: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed — SAVE THIS for future fee signing (Solana self-custody only) */
-    secret_key: string;
     /** Solana-compatible base58 address (Solana wallets only) */
     solana_address?: string;
     /** The wallet address (base58 for Solana, 0x for Ethereum) */
@@ -266,10 +344,8 @@ interface RegisterOptions {
     registrationToken?: string;
     /** Admin-minted invite token */
     registrationInvite?: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
-    walletSecretKey?: string;
-    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
-    walletModel?: 'self-custody' | 'operator';
+    /** Wallet model: 'operator' (Model B). Must be set explicitly to opt in. */
+    walletModel?: 'operator';
     /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
     walletChain?: 'solana' | 'ethereum';
     /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
@@ -295,20 +371,6 @@ interface RegisterOptions {
  * No wallet (default, single-phase):
  *   const creds = await register('my-agent', { registryUrl: '...' });
  *
- * Solana self-custody wallet (Model A, two-phase):
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletModel: 'self-custody',
- *   });
- *   // creds.wallet.secret_key = hex secret (SAVE THIS)
- *   // creds.wallet.address = base58 Solana address
- *
- * Solana with existing key:
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletSecretKey: '<hex-encoded-32-byte-seed>',
- *   });
- *
  * Ethereum bring-your-own (two-phase):
  *   const creds = await register('my-org', {
  *     registryUrl: '...',
@@ -358,6 +420,8 @@ interface BeatAgentConfig {
     verbose?: boolean;
     /** Verify anchor hash locally before trusting it (default: true). */
     verifyAnchors?: boolean;
+    /** Beats service URL for work-proof submission (default: https://beats.provenonce.dev). */
+    beatsUrl?: string;
 }
 declare class BeatAgent {
     private config;
@@ -371,6 +435,7 @@ declare class BeatAgent {
     private heartbeatInterval;
     private globalBeat;
     private globalAnchorHash;
+    private cachedIdentityClass;
     constructor(config: BeatAgentConfig);
     /**
      * Initialize the agent's Beat chain.
@@ -382,39 +447,28 @@ declare class BeatAgent {
         genesis?: string;
         error?: string;
     }>;
-    /**
-     * @deprecated Phase 2: VDF computation retired (D-68). Payment is the liveness mechanism.
-     * Use heartbeat() instead. This method will be removed in the next major version.
-     *
-     * Compute N beats locally (VDF hash chain).
-     */
-    pulse(count?: number): Beat[];
-    /** Internal beat computation — no status check. Used by both pulse() and resync(). */
+    /** Internal beat computation — no status check. Used by resync(). */
     private computeBeats;
-    /**
-     * @deprecated Phase 2: VDF check-in retired (D-68). Use heartbeat() instead.
-     * This method will be removed in the next major version.
-     */
-    checkin(): Promise<{
-        ok: boolean;
-        total_beats?: number;
-        error?: string;
-    }>;
     /**
      * Start the autonomous heartbeat loop.
      * Phase 2: Sends paid heartbeats at regular intervals.
      *
-     * @param paymentTxFn - Optional function that returns a payment tx for each heartbeat.
-     *                      If not provided, uses 'devnet-skip' (devnet only).
+     * @param paymentTxFn - Function that returns a Solana payment tx signature for each heartbeat (required).
      */
-    startHeartbeat(paymentTxFn?: () => Promise<string> | string): void;
+    startHeartbeat(paymentTxFn: () => Promise<string> | string): void;
     /**
      * Stop the heartbeat loop.
      */
     stopHeartbeat(): void;
     /**
-     * @deprecated Phase 2: Resync retired (D-67). Dormancy resume is free — just call heartbeat().
-     * This method will be removed in the next major version.
+     * Re-Sync Challenge (D-67 reversal): reactivate a frozen agent by proving CPU work.
+     *
+     * When BEATS_REQUIRED=true on the server: requires a signed Beats work-proof
+     * receipt. This method computes the proof automatically using computeWorkProof().
+     *
+     * When BEATS_REQUIRED=false (devnet): no receipt needed — agent is reactivated freely.
+     *
+     * Gap formula: min(gap_anchors * 100, 10_000) beats required (matches Beats constants).
      */
     resync(): Promise<{
         ok: boolean;
@@ -423,11 +477,47 @@ declare class BeatAgent {
     }>;
     /**
      * Request to spawn a child agent.
-     * Requires sufficient accumulated beats (Temporal Gestation).
+     * Requires sufficient accumulated beats (Temporal Gestation), OR a valid Beats work-proof receipt.
+     *
+     * @param childName    Optional name for the child agent
+     * @param childHash    Pre-registered child hash (Step 2 finalization)
+     * @param beatsReceipt Signed work-proof receipt from computeWorkProof() (receipt-based spawn)
+     */
+    requestSpawn(childName?: string, childHash?: string, beatsReceipt?: WorkProofReceipt): Promise<SpawnResult>;
+    /**
+     * Compute a Beats work-proof for spawn or resync authorization.
+     *
+     * Computes `beatsNeeded` sequential SHA-256 beats at `difficulty`, weaving in
+     * the given anchor hash, then submits to the Beats service and returns a signed receipt.
+     *
+     * @param opts.beatsNeeded  Minimum beats required (from spawn/resync response.required_beats)
+     * @param opts.anchorHash   Current global anchor hash (from syncGlobal or getAnchor)
+     * @param opts.anchorIndex  Current global anchor index
+     * @param opts.difficulty   Beat difficulty (default: agent's current difficulty)
+     */
+    computeWorkProof(opts: {
+        beatsNeeded: number;
+        anchorHash: string;
+        anchorIndex: number;
+        difficulty?: number;
+    }): Promise<WorkProofResult>;
+    /**
+     * Compute a Beats work-proof and use it to request spawn authorization.
+     *
+     * Probes the spawn endpoint to determine required beats, computes the proof,
+     * and returns the spawn_authorization token. The caller still needs to:
+     *   1. Register the child via POST /api/v1/register with spawn_authorization
+     *   2. Finalize via POST /api/v1/agent/spawn with child_hash
+     *
+     * @param opts.childName   Optional name for the child agent
+     * @param opts.beatsNeeded Override the required beats (default: auto-probed)
      */
-    requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
-    /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
-    private cachedProof;
+    requestSpawnWithBeatsProof(opts?: {
+        childName?: string;
+        beatsNeeded?: number;
+    }): Promise<SpawnResult>;
+    /** Cached passport from the most recent heartbeat or SIGIL purchase */
+    private cachedPassport;
     /**
      * Purchase a SIGIL (cryptographic identity) for this agent.
      * SIGILs gate heartbeating, lineage proofs, and offline verification.
@@ -440,6 +530,19 @@ declare class BeatAgent {
      * @param paymentTx - Solana transaction signature or 'devnet-skip'
      */
     purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
+    /**
+     * Get a SIGIL attribution token from a partner skill's ref_token (RFC-018).
+     *
+     * Call this after receiving a skill's ref_token in its response.
+     * Returns a pvr_ attribution token to include as `at` in purchaseSigil().
+     *
+     * This is the agent-side half of the two-sided witnessed proof:
+     * the skill's server already called /sigil/check for this agent hash.
+     * This call completes the proof — our server witnesses both sides.
+     *
+     * @param partnerRef - The skill's 16-char ref_token
+     */
+    getSigilAttribution(partnerRef: string): Promise<SigilAttributionResult>;
     /**
      * Update mutable SIGIL metadata fields.
      * Requires a SIGIL. Cannot modify immutable fields.
@@ -452,44 +555,102 @@ declare class BeatAgent {
      * Requires a SIGIL. Returns a signed lineage proof.
      * This is the Phase 2 replacement for pulse() + checkin().
      *
-     * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+     * @param paymentTx - Solana transaction signature (required).
      * @param globalAnchor - Optional: the global anchor index to reference.
      */
-    heartbeat(paymentTx?: string, globalAnchor?: number): Promise<HeartbeatResult>;
+    heartbeat(paymentTx: string, globalAnchor?: number, opts?: {
+        sponsoredBy?: string;
+    }): Promise<HeartbeatResult>;
     /**
-     * Reissue a lineage proof. "Reprint, not a renewal."
+     * Reissue a passport. "Reprint, not a renewal."
      * Does NOT create a new lineage event.
      *
-     * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+     * @param paymentTx - Solana transaction signature (required).
      */
-    reissueProof(paymentTx?: string): Promise<{
+    reissuePassport(paymentTx: string): Promise<{
         ok: boolean;
-        lineage_proof?: LineageProof;
+        passport?: Passport;
+        lineage_proof?: Passport;
+        error?: string;
+    }>;
+    /** @deprecated Use `reissuePassport()` instead. Sunset 2026-09-01. */
+    reissueProof(paymentTx: string): Promise<{
+        ok: boolean;
+        passport?: Passport;
+        lineage_proof?: Passport;
         error?: string;
     }>;
     /**
-     * Get the latest cached lineage proof (no network call).
-     * Returns null if no proof has been obtained yet.
+     * Sponsor a child agent's heartbeats.
+     * The authenticated agent (this instance) becomes the sponsor, paying heartbeat
+     * fees on behalf of the specified child from this agent's operator wallet.
+     *
+     * @param childHash - Hash of the child agent to sponsor
+     * @param opts.maxHeartbeatsEpoch - Max heartbeats per billing epoch (default: 100, max: 10,000)
+     * @param opts.expiresInHours - Optional TTL for the sponsorship
      */
-    getLatestProof(): LineageProof | null;
+    sponsorChild(childHash: string, opts?: {
+        maxHeartbeatsEpoch?: number;
+        expiresInHours?: number;
+    }): Promise<SponsorshipResult>;
     /**
-     * Get the agent's passport (alias for getLatestProof).
+     * Revoke a sponsorship for a child agent.
+     * The child will no longer be able to use this agent's wallet for heartbeat payments.
+     */
+    revokeSponsor(childHash: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * List all active sponsorships for this agent (as parent).
+     */
+    listSponsorships(): Promise<{
+        ok: boolean;
+        sponsorships?: SponsorshipRecord[];
+        error?: string;
+    }>;
+    /**
+     * Get the latest cached passport (no network call).
+     * Returns null if no passport has been obtained yet.
+     */
+    getLatestPassport(): Passport | null;
+    /** @deprecated Use `getLatestPassport()` instead. Sunset 2026-09-01. */
+    getLatestProof(): Passport | null;
+    /**
+     * Get the agent's passport (alias for getLatestPassport).
      * The passport is the agent's portable, offline-verifiable credential.
      * Returns null if no passport has been issued yet (requires SIGIL + heartbeat).
      */
     getPassport(): Passport | null;
     /**
-     * Verify a lineage proof locally using the authority public key.
+     * Export this agent's passport in both flat (Passport) and W3C VC envelope formats.
+     * Fetches a freshly signed passport from the server. Free endpoint, rate-limited 10/hr.
+     * Returns null if the request fails.
+     */
+    exportPassport(): Promise<{
+        passport: Passport;
+        passport_vc: ProvenoncePassportVC;
+        lineage_proof: Passport;
+    } | null>;
+    /**
+     * Wrap a Passport in a W3C Verifiable Credential envelope (client-side).
+     * Does not make any network call. Requires the passport to have authority_key_id.
+     */
+    static proofToPassportVC(proof: Passport, authorityKeyId?: string): ProvenoncePassportVC;
+    /**
+     * Verify a passport locally using the authority public key.
      * Offline verification — no API call, no SOL cost.
      *
      * Returns a VerificationResult object. The object is truthy when valid,
-     * so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
+     * so `if (BeatAgent.verifyPassportLocally(proof, key))` still works.
      *
-     * @param proof - The LineageProof to verify
+     * @param proof - The Passport to verify
      * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
      * @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
      */
-    static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
+    static verifyPassportLocally(proof: Passport, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
+    /** @deprecated Use `verifyPassportLocally()` instead. Sunset 2026-09-01. */
+    static verifyProofLocally(proof: Passport, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
     /**
      * Get this agent's full beat status from the registry.
      */
@@ -506,6 +667,12 @@ declare class BeatAgent {
         globalBeat: number;
         chainLength: number;
     };
+    /**
+     * Returns true if this agent has purchased a SIGIL in this session,
+     * or if a cached passport contains an identity_class.
+     * For an authoritative check, use GET /api/v1/agent/me.
+     */
+    hasSigil(): boolean;
     private syncGlobal;
     private refreshState;
     private api;
@@ -545,6 +712,7 @@ declare enum ErrorCode {
     VALIDATION = "VALIDATION",
     AUTH_INVALID = "AUTH_INVALID",
     AUTH_MISSING = "AUTH_MISSING",
+    SIGIL_REQUIRED = "SIGIL_REQUIRED",
     RATE_LIMITED = "RATE_LIMITED",
     AGENT_FROZEN = "AGENT_FROZEN",
     AGENT_NOT_INITIALIZED = "AGENT_NOT_INITIALIZED",
@@ -572,6 +740,10 @@ declare class ValidationError extends ProvenonceError {
 declare class AuthError extends ProvenonceError {
     constructor(message: string, code?: ErrorCode.AUTH_INVALID | ErrorCode.AUTH_MISSING, statusCode?: number);
 }
+/** Thrown on 403 SIGIL_REQUIRED — agent has not purchased a SIGIL */
+declare class SigilRequiredError extends ProvenonceError {
+    constructor(message?: string);
+}
 /** Thrown on 429 — rate limit exceeded */
 declare class RateLimitError extends ProvenonceError {
     /** Milliseconds until the rate limit resets (if provided by server) */
@@ -601,4 +773,4 @@ declare class ServerError extends ProvenonceError {
     constructor(message: string, statusCode?: number);
 }
 
-export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegisterOptions, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register, verifyAnchorHash };
+export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, type ProvenoncePassportVC, RateLimitError, type RegisterOptions, type RegistrationResult, ServerError, type SigilAttributionResult, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, SigilRequiredError, type SigilResult, type SigilTier, type SpawnResult, type SponsorshipRecord, type SponsorshipResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, type WorkProofReceipt, type WorkProofResult, computeBeat, computeBeatsLite, register, verifyAnchorHash };