zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/build/permitsClient.d.ts

@@ -0,0 +1,680 @@
+import { type ApplicationRecord, type PermitRecord, type PermitStatusName } from './permitRegistryRebuild.js';
+import type { DescribeContext, PermitMessageDescription } from './permitDescribe.js';
+import type { PurchaseReceipt } from './receipt.js';
+/** One row of GET /permits/registries/:address/transactions (amounts in nanomina, as strings). */
+export type RegistryTransaction = {
+    date: string;
+    slot: number;
+    kind: 'permit' | 'renewal' | 'rejected' | 'withdrawn' | 'refunded after deadline';
+    subject: string;
+    amount: string;
+    authorityShare: string;
+    platformShare: string;
+    refunded: string;
+    txHash: string | null;
+};
+/** GET /permits/registries/:address/stats (amounts in nanomina, as strings). */
+export type RegistryStats = {
+    registry: string;
+    name: string;
+    network: string;
+    slot: number;
+    listing: 'listed' | 'pending' | 'delisted';
+    permits: {
+        total: number;
+        byStatus: Record<string, number>;
+    };
+    applications: Record<string, number>;
+    fees: {
+        grants: number;
+        grantFees: string;
+        renewals: number;
+        renewalFees: string;
+        processingFees: string;
+        refunded: string;
+        gross: string;
+        platformShare: string;
+        authorityShare: string;
+    };
+    byMonth: Array<{
+        month: string;
+        grants: number;
+        renewals: number;
+        fees: string;
+    }>;
+};
+export type Network = 'devnet' | 'mainnet';
+/** What the client needs from a wallet. */
+export interface PermitWallet {
+    readonly address: string;
+    /** Field signature (Auro `signFields`), base58. */
+    signFields(fields: string[]): Promise<string>;
+    /** Text signature (Auro `signMessage`). */
+    signMessage(message: string): Promise<{
+        field: string;
+        scalar: string;
+    }>;
+    /** Signs a keeper-proved transaction as fee payer and broadcasts it; returns the hash. */
+    signAndSendTransaction(transactionJson: string): Promise<string>;
+}
+export declare class PermitsError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly body: unknown;
+    constructor(message: string, status: number, code: string, retryable: boolean, body?: unknown);
+}
+/** The sign-in text: names the site and network (the keeper's challenge
+ * supplies both), so a sign-in for devnet never works on mainnet. */
+export declare function sessionMessage(address: string, nonce: string, issuedAt: string, network: string, site: string): string;
+/**
+ * An authority's details. On mainnet `registrationNumber` (organisation
+ * number) and `billingAddress` are required; `vatId` only when the
+ * organisation is VAT-registered (it is then checked, with VIES for EU
+ * numbers). Without one, the platform's fee includes VAT.
+ */
+export type AuthorityDetails = {
+    legalName: string;
+    country: string;
+    website: string;
+    contactEmail: string;
+    registrationNumber?: string;
+    vatId?: string;
+    billingAddress?: {
+        line1: string;
+        line2?: string;
+        city: string;
+        postalCode: string;
+    };
+};
+export declare function authorityAcceptanceMessage(f: {
+    address: string;
+    legalName: string;
+    country: string;
+    termsVersion: string;
+    termsHash: string;
+    acceptedAt: string;
+}): string;
+export type PermitsClientOptions = {
+    keeperUrl: string;
+    network: Network;
+    wallet?: PermitWallet;
+    fetcher?: typeof fetch;
+    /**
+     * Called before every field signature (wallets show those as numbers):
+     * with what the numbers mean, checked against them
+     * (zklicensing/permits/describe). Return false to cancel. Unverified
+     * descriptions are refused before this is called.
+     */
+    confirmSignature?: (d: PermitMessageDescription) => Promise<boolean | void> | boolean | void;
+    /** Labels for the descriptions: activity names and dates, per registry. */
+    describeContext?: (registry: string) => Promise<DescribeContext> | DescribeContext;
+};
+export type RequestView = {
+    id: string;
+    registry: string;
+    kind: string;
+    message: string[];
+    keys: string[];
+    required: number;
+    signatures: Record<string, string>;
+    status: string;
+    salt?: string;
+    fee?: string;
+    oldLeaf?: PermitRecord;
+    newLeaf?: PermitRecord;
+    reasonCode?: string;
+    newFeesPacked?: string;
+    newAppTermsPacked?: string;
+    newKeys?: string[];
+    newThreshold?: number;
+    /** payout: the address proposed; payoutCancel: the one cancelled. */
+    newPayout?: string;
+    /** rotate: every new key's signature, by its slot in the new set. */
+    newSignatures?: Record<string, string>;
+    /** approveApplication / rejectApplication: the application as filed. */
+    application?: ApplicationRecord;
+    applicationId?: string;
+    /** The transaction that carried it out, once sent. */
+    txHash?: string;
+};
+export declare function createPermitsClient(opts: PermitsClientOptions): {
+    network: Network;
+    signIn: () => Promise<string>;
+    listRegistries: () => Promise<{
+        registries: any[];
+    }>;
+    getRegistry: (address: string) => Promise<{
+        registry: any;
+        chain?: any;
+    }>;
+    /** The registry's lineage (its first generation's address), which holder secrets are derived against. */
+    registryLineage: (address: string) => Promise<string>;
+    /**
+     * A permit with a witness against its registry's root. Asked through an
+     * earlier generation's address, it comes from the current one
+     * (`registry`, `generation`), which starts with every permit of the one it
+     * replaced.
+     */
+    getPermit: (registry: string, subject: string) => Promise<{
+        permit: PermitRecord | null;
+        status: PermitStatusName;
+        slot: number;
+        root: string;
+        witness: {
+            isLefts: boolean[];
+            siblings: string[];
+        };
+        registry?: string;
+        generation?: number;
+        frozen?: boolean;
+    }>;
+    /** A registry's generations and release, and any redeploy under way (no events needed). */
+    getDeployment: (registry: string) => Promise<{
+        registry: string;
+        network: string;
+        generation: number;
+        status: string;
+        current: string;
+        generations: Array<{
+            generation: number;
+            address: string;
+            status: string;
+            retiredAt?: string;
+        }>;
+        currentVerificationKeyHash: string;
+        chain: {
+            verificationKeyHash: string | null;
+            current: boolean;
+            retired: boolean;
+            hasPermits: boolean;
+            hasOpenApplications: boolean;
+        } | null;
+        /** draining: open applications settle first (no new filings); then successor and the two requests. */
+        redeploy: {
+            startedAt: string;
+            draining?: boolean;
+            openApplications?: number;
+            lastDeadline?: number | null;
+            successor?: any;
+            request?: RequestView | null;
+            retireRequest?: RequestView | null; /** The platform key retires it (retireByPlatform): the keys sign only the new registry. */
+            byPlatform?: boolean;
+        } | null;
+    }>;
+    verifyPermit: (registry: string, subject: string, scope?: bigint | string) => Promise<{
+        valid: boolean;
+        status: PermitStatusName;
+        scopeOk: boolean;
+        slot: number;
+        root: string;
+        permit: any;
+    }>;
+    getRequest: (id: string, asSelf?: boolean) => Promise<{
+        request: RequestView;
+    }>;
+    /** `agentConsent`: the owner's standing consent when an AI agent's key accepts for them. */
+    acceptAuthorityTerms(f: AuthorityDetails & {
+        termsVersion: string;
+        termsHash: string;
+        agentConsent?: unknown;
+    }): Promise<{
+        authority: any;
+    }>;
+    /**
+     * The platform's monthly fee statement for this wallet's registries
+     * (`month` YYYY-MM): its share of each permit fee, in euros, with VAT as
+     * the authority's details require. null when nothing to show.
+     */
+    /**
+     * What forced retirements left in escrow on this wallet's registries
+     * (Authority Terms §8.4): per registry, the applications whose fees stay
+     * there, their payers and the total.
+     */
+    authorityStranded: () => Promise<{
+        registries: Array<{
+            registry: string;
+            name: string | null;
+            successor: string | null;
+            retireTxHash: string;
+            strandedAt: string;
+            count: number;
+            totalNano: string;
+            applications: Array<{
+                id: string;
+                holderKey: string;
+                payer: string | null;
+                feeNano: string;
+                deadline: number | null;
+                contactEmail: string;
+            }>;
+        }>;
+        count: number;
+        totalNano: string;
+    }>;
+    authorityFeeStatement: (month: string) => Promise<any>;
+    /**
+     * This wallet's receipts and credit notes for a license (zklicensing/receipt),
+     * purchase first; signs in with the wallet (a receipt shows the buyer's country).
+     */
+    getLicenseReceipts: (zkAppAddress: string, licenseHash: string) => Promise<PurchaseReceipt[]>;
+    /** This wallet's receipt or credit note for one transaction (a license or a permit fee). */
+    getReceipt: (txHash: string) => Promise<PurchaseReceipt>;
+    /**
+     * This wallet as a holder: its applications, its permits (with their
+     * effective status; a redeployed registry's earlier permits are marked
+     * frozen) and renewals offered to it that wait for acceptGrant.
+     */
+    getHolderOverview: () => Promise<{
+        network: string;
+        slot: number;
+        applications: Array<{
+            id: string;
+            registry: string;
+            registryName: string;
+            status: string;
+            createdAt: string;
+            requestedScope: string;
+            terms: any | null;
+            escrow: any | null;
+            settlement: any | null;
+        }>;
+        permits: Array<PermitRecord & {
+            registry: string;
+            registryName: string;
+            generation: number;
+            frozen: boolean;
+            effectiveStatus: PermitStatusName;
+        }>;
+        offers: Array<{
+            id: string;
+            registry: string;
+            registryName: string;
+            newLeaf: PermitRecord;
+            fee: string;
+            createdAt: string;
+        }>;
+    }>;
+    /** This wallet's authority account (404 NOT_FOUND before the terms are accepted). */
+    getAuthority: () => Promise<{
+        authority: any;
+        currentTerms: {
+            version: string;
+            hash: string;
+        };
+    }>;
+    /** Registries this wallet is an authority of, including drafts. */
+    listMyRegistries: () => Promise<{
+        registries: any[];
+    }>;
+    listRequests: (registry: string, status?: string) => Promise<{
+        requests: RequestView[];
+    }>;
+    createRegistry: (draft: {
+        name: string;
+        website: string;
+        jurisdiction?: string;
+        description?: string;
+        keys: string[];
+        threshold: number;
+        scopes: Array<{
+            bit: number;
+            label: string;
+        }>;
+        policy?: {
+            gracePeriod?: number;
+            maxTerm?: number;
+            singleKeySuspend?: boolean;
+            holderSigRequired?: boolean;
+        };
+        grantFeeMina: string;
+        renewalFeeMina?: string;
+        payout?: string;
+        /** Kept when an application is rejected or withdrawn (default the platform minimum); decision window in slots (default 14 days). */
+        processingFeeMina?: string;
+        decisionWindow?: number;
+    }) => Promise<{
+        registry: any;
+        request: RequestView;
+    }>;
+    /**
+     * Changes a registry's public details (authority). On devnet they apply
+     * at once; on a listed mainnet registry they wait for the platform's
+     * review (`staged: true`). `scopeLabels` rewords the activities, one label
+     * each in order; the activities themselves can't change.
+     */
+    updateRegistryListing: (registry: string, edit: {
+        name?: string;
+        description?: string;
+        jurisdiction?: string;
+        scopeLabels?: string[];
+    }) => Promise<{
+        registry: any;
+        staged: boolean;
+    }>;
+    /** Stops (false) or resumes (true) taking applications (authority); everything else carries on. */
+    setApplicationsOpen: (registry: string, open: boolean) => Promise<{
+        registry: any;
+    }>;
+    /** Withdraws a staged edit of a registry's public details (authority). */
+    withdrawRegistryEdit: (registry: string) => Promise<{
+        registry: any;
+    }>;
+    /** A registry's figures for its authority: permits and applications by status, fees by kind and month (nanomina). */
+    getRegistryStats: (registry: string) => Promise<RegistryStats>;
+    /** The registry's money events (authority), oldest first: `from`/`to` as YYYY-MM-DD, `to` exclusive. Amounts in nanomina. */
+    getRegistryTransactions: (registry: string, period?: {
+        from?: string;
+        to?: string;
+    }) => Promise<{
+        registry: string;
+        network: string;
+        transactions: RegistryTransaction[];
+    }>;
+    /** Signs a request with this wallet's key and adds the signature at `slot`. */
+    signRequest(requestId: string, slot?: number): Promise<{
+        request: RequestView;
+    }>;
+    /**
+     * Starts a redeploy to the current release: a new registry (same
+     * configuration, next generation) and two requests for the keys to sign,
+     * `retireRequest` (freezes this registry's permits on chain) and `request`
+     * (deploys the new one). Send them in that order: executeRequest(retire),
+     * then deployRegistry(request). The new registry starts with every permit
+     * of this one, as it is when it retires. With fees in escrow
+     * (ESCROW_NOT_EMPTY) only the platform can start a redeploy: the registry
+     * then drains
+     * (`draining: true`): no new filings while the open ones are decided,
+     * withdrawn or reclaimed; call again once they are, to get the requests.
+     */
+    redeployRegistry: (registry: string) => Promise<{
+        successor: any;
+        retireRequest: RequestView | null;
+        retiredByPlatform?: boolean;
+        request: RequestView;
+    } | {
+        draining: true;
+        openApplications: number;
+        lastDeadline: number | null;
+    }>;
+    /** Calls off a redeploy whose retirement hasn't been sent. */
+    cancelRedeploy: (registry: string) => Promise<{
+        registry: any;
+    }>;
+    /** Proves the deployment, signs and pays with this wallet, and reports it. */
+    deployRegistry(requestId: string): Promise<{
+        registry: string;
+        txHash: string;
+    }>;
+    listApplications: (registry: string, status?: string) => Promise<{
+        applications: any[];
+        paymentPaused?: boolean;
+    }>;
+    /**
+     * Approves a filed application exactly as applied for (the permit is
+     * active once the request is signed and sent): a request for the
+     * authority keys to sign, then executeRequest. An unpaid one whose
+     * payment waits for a Mina upgrade is approved before payment (no
+     * request): the keeper raises the request once its fee is in escrow,
+     * and the applicant learns of it then.
+     */
+    approveApplication: (id: string) => Promise<{
+        application: any;
+        request?: RequestView;
+    }>;
+    /**
+     * Rejects a filed application: the processing fee is kept, the rest
+     * refunded once the request is signed and sent. An unpaid one whose
+     * payment waits for a Mina upgrade is rejected before payment (no
+     * request): the keeper raises the request once its fee is in escrow,
+     * and the applicant learns of it then. `reason` stays off chain.
+     */
+    rejectApplication: (id: string, reason?: string, reasonCode?: string) => Promise<{
+        application: any;
+        request?: RequestView;
+    }>;
+    requestRenewal: (registry: string, subject: string, change: {
+        expirySlot: number | "none";
+        scope?: string;
+        validFrom?: number;
+        docHash?: string;
+    }) => Promise<{
+        request: RequestView;
+    }>;
+    requestStatus: (registry: string, subject: string, action: "suspend" | "reinstate" | "revoke", reasonCode?: string) => Promise<{
+        request: RequestView;
+    }>;
+    /** New fees; the processing fee (MINA) and decision window (slots) stay as they are unless given. */
+    requestFees: (registry: string, grantFeeMina: string, renewalFeeMina?: string, applications?: {
+        processingFeeMina?: string;
+        decisionWindow?: number;
+    }) => Promise<{
+        request: RequestView;
+    }>;
+    requestRotation: (registry: string, keys: string[], threshold: number) => Promise<{
+        request: RequestView;
+    }>;
+    /** Proves a fully signed non-grant request, signs and pays with this wallet, and reports it. */
+    executeRequest(requestId: string): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Applies for a permit and pays the fee into escrow (`pay: false` only
+     * records the application; file it later with fileApplication). What is
+     * applied for is what an approval grants: activities (`scope`), dates and
+     * conditions document. Rejection or withdrawal keeps the registry's
+     * processing fee and refunds the rest to the payer; no decision by the
+     * deadline refunds it all.
+     *
+     * A new permit's secret for anonymous proofs (zklicensing/permits/holder-secret)
+     * is derived by the holder's wallet from a counter, the first not yet
+     * used by this key in the registry; only the salt (a hash of the secret)
+     * goes to the keeper. The wallet signs once per counter tried. When
+     * another key is the holder, derive with that key's wallet
+     * (deriveHolderSecret), pass `salt` and `pay: false`, and let the holder
+     * file it. To renew or change your active permit, pass its `subject`.
+     */
+    apply(registry: string, a: {
+        scope?: string;
+        requestedScope?: string;
+        expirySlot?: number | "none";
+        validFrom?: number;
+        docHash?: string;
+        details?: Record<string, unknown>;
+        docLinks?: string[];
+        contactEmail?: string;
+        holderKey?: string;
+        salt?: string;
+        subject?: string;
+        pay?: boolean;
+        payer?: PermitWallet;
+    }): Promise<{
+        application: any;
+        apply: any;
+        txHash?: string;
+        fee?: string;
+        processingFee?: string;
+        deadline?: number;
+        paymentPaused?: {
+            reason: string;
+            forkActivationSlot: number | null;
+        };
+    }>;
+    getApplication: (id: string) => Promise<{
+        application: any;
+        request: RequestView | null;
+        slot: number | null;
+        apply: {
+            application: ApplicationRecord;
+            fee: string;
+            processingFee: string;
+            decisionWindow: number;
+            message: string[];
+            /** Not payable now (ahead of a Mina upgrade, or while the registry moves): it is kept and paid afterwards, on the new registry. */
+            paymentPaused?: {
+                reason: "upgrade" | "redeploy";
+                forkActivationSlot: number | null;
+            };
+        } | null;
+        withdrawMessage?: string[];
+        reclaimable?: boolean | null;
+    }>;
+    /**
+     * The holder signs what is applied for (with the registry's current fee
+     * and processing fee) and `payer` (default: this wallet) pays the fee
+     * into escrow. Returns the deadline slot for the authority's decision.
+     */
+    fileApplication(id: string, payer?: PermitWallet): Promise<{
+        txHash: string;
+        fee: string;
+        processingFee: string;
+        deadline: number;
+    }>;
+    /**
+     * Withdraws an application. Unpaid: recorded off chain. Paid (filed),
+     * before the deadline: the holder signs, the processing fee is kept and
+     * the rest goes back to the payer; this wallet pays the transaction fee.
+     */
+    withdrawApplication(id: string): Promise<{
+        application: any;
+    } | {
+        receipt?: PurchaseReceipt | undefined;
+        application: any;
+        txHash: string;
+        kept: string;
+        refunded: string;
+    }>;
+    /** After the deadline without a decision: returns the whole fee to the payer. Any wallet can send it (it pays the transaction fee). */
+    reclaimApplication(id: string, sender?: PermitWallet): Promise<{
+        txHash: string;
+        refunded: string;
+        payer: string;
+    }>;
+    /**
+     * The holder accepts a signed grant: signs the exact permit and fee,
+     * then pays with `payer` (default: this wallet). The holder's wallet can
+     * re-derive the permit's secret for anonymous proofs at any time
+     * (findHolderSecret), from the chain alone.
+     */
+    acceptGrant(requestId: string, payer?: PermitWallet): Promise<{
+        receipt?: PurchaseReceipt | undefined;
+        txHash: string;
+        subject: string;
+        fee: string;
+        toAuthority: string;
+        toPlatform: string;
+    }>;
+    /**
+     * A new payout address for the registry (authority): a request for the
+     * keys to sign; once sent it takes effect after 48 hours, unless
+     * cancelled (cancelRegistryPayout). The keeper applies it then.
+     */
+    proposeRegistryPayout: (registry: string, payout: string) => Promise<{
+        request: RequestView;
+    }>;
+    /** Cancels the pending payout change: a request for the keys to sign. */
+    cancelRegistryPayout: (registry: string) => Promise<{
+        request: RequestView;
+    }>;
+    /** Applies a payout change past its delay, paid by this wallet (the keeper does it itself when it has a fee payer). */
+    applyRegistryPayout(registry: string): Promise<{
+        txHash: string;
+        payout: string;
+    }>;
+    /**
+     * Signs a key rotation as one of the NEW keys (`newSlot`: its place in
+     * the new set). Every new key signs, besides the current keys' threshold.
+     */
+    signRotationAsNewKey(requestId: string, newSlot?: number): Promise<{
+        request: RequestView;
+    }>;
+    /**
+     * Moves the holder's permit to `newWallet`'s key (both keys sign; free):
+     * the same terms under a new subject, whose secret the new wallet derives
+     * itself (its first unused counter in the registry's lineage). This
+     * wallet pays the fee unless `payer` is given.
+     */
+    rekeyPermit(registry: string, subject: string, newWallet: PermitWallet, payer?: PermitWallet): Promise<{
+        txHash: string;
+        subject: string;
+        salt: string;
+    }>;
+    /** Moves this wallet's authority account to `newWallet` (both sign); registry keys change by a rotation. */
+    moveAuthorityAccount(newWallet: PermitWallet): Promise<{
+        moved: {
+            from: string;
+            to: string;
+        };
+    }>;
+    /** The holder gives up their permit. */
+    surrender(registry: string, subject: string): Promise<{
+        txHash: string;
+    }>;
+};
+export type PermitsClient = ReturnType<typeof createPermitsClient>;
+/**
+ * The registry's permits root and the current slot, read from a Mina node
+ * (not the keeper) — what a verifier of a holder proof should accept as
+ * `acceptedRoots` / `currentSlot` in `verifyHolderProof`.
+ */
+export declare function readRegistryHead(args: {
+    registry: string;
+    network: Network;
+    graphqlUrl?: string;
+    fetcher?: typeof fetch;
+}): Promise<{
+    root: string;
+    slot: number;
+}>;
+/**
+ * The current registry of `registry`'s lineage, from chain state alone: a
+ * retired registry names its successor (stored by its retirement, which its
+ * keys signed), and the successor's initialization checked the
+ * predecessor named it. Each hop also checks the successor runs a published
+ * PermitRegistry release and started from the predecessor's frozen root. A
+ * successor not deployed yet (between retirement and deployment, e.g.
+ * across a hard fork) leaves the retired registry current.
+ */
+export declare function currentRegistryOnChain(args: {
+    registry: string;
+    network: Network;
+    graphqlUrl?: string;
+    fetcher?: typeof fetch;
+}): Promise<string>;
+/**
+ * Verifies a permit without trusting the keeper: the root comes from
+ * `fetchRoot` (default: the registry account's appState[0] read from a
+ * Mina node), and the keeper's leaf and witness must fold to that root.
+ */
+export declare function verifyPermitTrustless(args: {
+    keeperUrl: string;
+    network: Network;
+    registry: string;
+    subject: string;
+    requiredScope?: bigint;
+    /** Current slot for the date check; default the node's slot (or the keeper's with a custom fetchRoot). */
+    slot?: number;
+    gracePeriod?: number;
+    fetchRoot?: (registry: string) => Promise<string>;
+    /** Mina node for the default root and slot read. */
+    graphqlUrl?: string;
+    fetcher?: typeof fetch;
+}): Promise<{
+    valid: boolean;
+    status: PermitStatusName;
+    scopeOk: boolean;
+    rootMatches: boolean;
+    permit: PermitRecord | null;
+    registry: string;
+    frozen: boolean;
+}>;
+/**
+ * A wallet for scripts and agents, from a private key the owner handed over.
+ * `send` broadcasts the signed transaction (default: o1js on the active
+ * Mina instance). Requires the optional `mina-signer` peer dependency.
+ */
+export declare function minaSignerWallet(privateKeyBase58: string, opts: {
+    network: Network;
+    send?: (signedZkappCommandJson: unknown) => Promise<string>;
+}): Promise<PermitWallet>;
+//# sourceMappingURL=permitsClient.d.ts.map