@provenonce/sdk 0.14.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

@@ -40,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;
@@ -56,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;
@@ -65,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;
@@ -77,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;
@@ -105,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;
@@ -139,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;
@@ -149,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 {
@@ -369,6 +435,7 @@ declare class BeatAgent {
     private heartbeatInterval;
     private globalBeat;
     private globalAnchorHash;
+    private cachedIdentityClass;
     constructor(config: BeatAgentConfig);
     /**
      * Initialize the agent's Beat chain.
@@ -386,10 +453,9 @@ declare class BeatAgent {
      * 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.
      */
@@ -450,8 +516,8 @@ declare class BeatAgent {
         childName?: string;
         beatsNeeded?: number;
     }): Promise<SpawnResult>;
-    /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
-    private cachedProof;
+    /** 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.
@@ -464,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.
@@ -476,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).
+     */
+    reissuePassport(paymentTx: string): Promise<{
+        ok: boolean;
+        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;
+    }>;
+    /**
+     * 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
      */
-    reissueProof(paymentTx?: string): Promise<{
+    sponsorChild(childHash: string, opts?: {
+        maxHeartbeatsEpoch?: number;
+        expiresInHours?: number;
+    }): Promise<SponsorshipResult>;
+    /**
+     * 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;
-        lineage_proof?: LineageProof;
         error?: string;
     }>;
     /**
-     * Get the latest cached lineage proof (no network call).
-     * Returns null if no proof has been obtained yet.
+     * List all active sponsorships for this agent (as parent).
      */
-    getLatestProof(): LineageProof | null;
+    listSponsorships(): Promise<{
+        ok: boolean;
+        sponsorships?: SponsorshipRecord[];
+        error?: string;
+    }>;
     /**
-     * Get the agent's passport (alias for getLatestProof).
+     * 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.
      */
@@ -530,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;
@@ -569,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",
@@ -596,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) */
@@ -625,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, type WorkProofReceipt, type WorkProofResult, computeBeat, computeBeatsLite, 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 };