@chipi-stack/backend 14.6.0 → 14.8.0

package/dist/index.d.mts

@@ -281,6 +281,143 @@ declare class ChipiExchanges {
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken: string): Promise<number>;
 }
 
+/**
+ * SHHH multisig treasury coordination client (Plus Wave 9 / P1).
+ *
+ * A thin, typed HTTP client for the chipi-back `/v1/treasuries/:id/...`
+ * endpoints. It implements the same transport contract `@chipi-stack/chipi-react`
+ * injects into `useProposeAction` / `useTreasuryProposals` (`MultisigTransport`),
+ * so an integrator can wire `sdk.treasury.forTreasury(...)` straight into those
+ * hooks instead of hand-writing fetch glue.
+ *
+ * Auth model (decision §11.2 — owner-signature-as-authorization):
+ *   - propose / sign: `pk_` (the public api key) PLUS the owner's V2_SNIP12
+ *     envelope (already inside the proposal body) AND the owner's STARK
+ *     `ownerPubkey`. chipi-back's OwnerSignatureVerifier proves the request
+ *     came from a current on-chain owner, so no secret is needed — these are
+ *     safe to call from the browser.
+ *   - execute / list / allowance: `sk_` (a secret key bearer). execute relays
+ *     through the paymaster and meters; reads are org-private. Call these from
+ *     a server (a Next.js route handler / your backend), never the browser.
+ *
+ * The types below mirror `@chipi-stack/chipi-react/multisig`'s `TreasuryProposal`
+ * / `ProposeBody` field-for-field (post-#324: OE `executeAfter` is derived from
+ * `executeBefore`, never sent or stored). They're duplicated (not imported) so
+ * the server SDK never depends on the React package; TypeScript's structural
+ * typing makes a `TreasuryTransport` assignable to the hook's `MultisigTransport`.
+ */
+/** One owner's collected signature on a proposal. */
+interface TreasuryProposalSignature {
+    ownerId: number;
+    signerKind: string;
+    /** The owner's serialized inner V2_SNIP12 envelope (comma-joined felts). */
+    signature: string;
+}
+/** A treasury proposal as returned by the coordination backend. */
+interface TreasuryProposal {
+    id: string;
+    /** Set for generalized actions (vote / call any contract); null for payments. */
+    calls?: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[] | null;
+    /** Human label for an action ("Vote YES on Proposal #5"). */
+    title?: string | null;
+    /** Arbitrary integrator context. chipi-back has no column for it today, so
+     *  it is absent on every proposal it returns (kept for contract parity). */
+    meta?: Record<string, string | number> | null;
+    oeMessageHash: string;
+    oeNonce: string | null;
+    /** chipi-back persists only `oeExecuteBefore`; the OE `executeAfter` is
+     *  re-derived as `executeBefore - 2h` by executors (see chipi-react #324). */
+    oeExecuteBefore: string | null;
+    requiredApprovals: number;
+    status: "PROPOSED" | "APPROVED" | "EXECUTED" | "CANCELED" | "EXPIRED";
+    executedTxHash?: string | null;
+    signatures: TreasuryProposalSignature[];
+}
+/** The body the coordination backend's `propose` endpoint accepts. */
+interface ProposeBody {
+    proposerOwnerId: number;
+    recipient: string;
+    tokenAddress: string;
+    amount: string;
+    title: string;
+    calls: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[];
+    /** Arbitrary integrator context. NOTE: not persisted by chipi-back today
+     *  (no column) — the global ValidationPipe strips it. Kept for parity. */
+    meta?: Record<string, string | number>;
+    oeMessageHash: string;
+    oeNonce: string;
+    oeExecuteBefore: string;
+    requiredApprovals: number;
+    proposerSignature: string;
+    proposerSignerKind: string;
+}
+/** The approver's body for `sign` (mirrors chipi-react's call site). */
+interface ApproveBody {
+    ownerId: number;
+    signature: string;
+    signerKind: string;
+}
+/** Result of relaying an execute through the paymaster. */
+interface ExecuteResult {
+    executedTxHash?: string;
+    transactionHash?: string;
+}
+/** Free-execute meter for the org (shape owned by chipi-back's treasury svc). */
+interface MultisigAllowance {
+    freeExecutesRemaining?: number;
+    priceUsd?: number;
+    creditsUsd?: number;
+    canExecuteNow?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * A transport bound to one treasury + the local owner's STARK pubkey.
+ * Structurally compatible with `@chipi-stack/chipi-react`'s `MultisigTransport`.
+ */
+interface TreasuryTransport {
+    list(): Promise<{
+        items: TreasuryProposal[];
+    }>;
+    propose(body: ProposeBody): Promise<TreasuryProposal>;
+    sign(proposalId: string, body: ApproveBody): Promise<unknown>;
+    execute(proposalId: string, calldata: string[]): Promise<ExecuteResult>;
+    /** Read the org's free-execute meter (sk_). Not part of MultisigTransport. */
+    getMultisigAllowance(): Promise<MultisigAllowance>;
+}
+interface ForTreasuryConfig {
+    /** The org treasury id (the multisig wallet's row id in chipi-back). */
+    treasuryId: string;
+    /** The local owner's STARK public key (one 0x-hex felt). Sent with propose /
+     *  sign so the backend can verify the envelope commits to a current owner. */
+    ownerPubkey: string;
+    /** A secret key (`sk_`) for execute / list / allowance. Falls back to the
+     *  SDK's configured `apiSecretKey`. Required only for those three; propose /
+     *  sign authenticate with `pk_` + the owner signature. */
+    bearerToken?: string;
+}
+declare class ChipiTreasury {
+    private client;
+    private apiSecretKey?;
+    constructor(client: ChipiClient, apiSecretKey?: string | undefined);
+    private base;
+    /** Resolve a `sk_` for the secret-gated reads/execute, or fail loudly. */
+    private secret;
+    /**
+     * Build a {@link TreasuryTransport} for one treasury + owner. Wire the
+     * returned object directly into chipi-react's `useProposeAction` /
+     * `useTreasuryProposals` `transport` prop, or call its methods yourself.
+     */
+    forTreasury(config: ForTreasuryConfig): TreasuryTransport;
+}
+
 /**
  * PaymasterAdapter implementation that uses Chipi's backend API for gasless transactions.
  *
@@ -382,6 +519,7 @@ declare class ChipiSDK {
     readonly skus: ChipiSkus;
     readonly sessions: ChipiSessions;
     readonly exchanges: ChipiExchanges;
+    readonly treasury: ChipiTreasury;
     constructor(config: ChipiSDKConfig);
     /**
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -481,7 +619,7 @@ declare class ChipiSDK {
      * });
      * ```
      */
-    signTypedData({ params, }: {
+    signTypedData({ params }: {
         params: SignTypedDataParams;
     }): Promise<SignTypedDataResult>;
     /**
@@ -1142,6 +1280,51 @@ declare function buildEd25519Envelope(params: {
      */
     ownerIndex?: bigint;
 }): Promise<bigint[]>;
+/**
+ * Build a V2_SNIP12 Ed25519 envelope from an **externally-produced**
+ * signature — the Phantom / Solana flow. Phantom (and every external
+ * Ed25519 wallet) never exposes the private key: the user signs via
+ * `window.solana.signMessage(...)`, which returns a 64-byte signature
+ * (R‖s). This is the from-signature counterpart of
+ * `buildEd25519Envelope`, mirroring `buildEip191EnvelopeFromSignature`
+ * for MetaMask.
+ *
+ * IMPORTANT — what the wallet MUST sign:
+ *   The wallet must sign the EXACT bytes returned by
+ *   `ed25519SignedBytes(messageHash)` — the 64-byte hex-ASCII encoding
+ *   of the SNIP-12 OE hash — NOT the raw 32-byte `messageHash`. The
+ *   Cairo verifier reconstructs those same bytes from `messageHash`, so
+ *   a mismatch fails on chain. The dashboard adapter does:
+ *     await window.solana.connect();
+ *     // Phantom returns the 32-byte Ed25519 pubkey as a Solana PublicKey;
+ *     // `.toBytes()` is the Uint8Array this API expects.
+ *     const publicKey = window.solana.publicKey.toBytes();
+ *     const msg = ed25519SignedBytes(messageHash);
+ *     // Phantom's signMessage returns { signature: Uint8Array (64B), publicKey }.
+ *     const { signature } = await window.solana.signMessage(msg);
+ *     const env = await buildEd25519EnvelopeFromSignature({
+ *       signature, publicKey, messageHash,
+ *     });
+ *
+ * Async (unlike the synchronous EIP-191 from-signature path): the
+ * Garaga WASM hint builder must be initialized to produce the EC hints
+ * the Cairo Ed25519 verifier needs. The issue sketch (#311) showed a
+ * sync return; Ed25519 cannot avoid the WASM init that secp256k1 does.
+ */
+declare function buildEd25519EnvelopeFromSignature(params: {
+    /** 64-byte Ed25519 signature R(32)‖s(32) from the wallet's signMessage. */
+    signature: Uint8Array;
+    /** 32-byte Ed25519 public key (as Phantom returns it). */
+    publicKey: Uint8Array;
+    /** SNIP-12 hash of the OutsideExecution — see oe.ts::computeOeHash. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * MUST fit in u32. Same semantics + footgun as `buildEd25519Envelope`:
+     * pass the INDEX, never an `ed25519OwnerId` commitment.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
 
 /**
  * EIP-191 secp256k1 signer for SHHH V8.4 ShhhAccount.
@@ -2203,4 +2386,4 @@ declare function executeShhhSponsoredRaw(params: {
     chainId?: bigint | string;
 }): Promise<string>;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };

package/dist/index.d.ts

@@ -281,6 +281,143 @@ declare class ChipiExchanges {
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken: string): Promise<number>;
 }
 
+/**
+ * SHHH multisig treasury coordination client (Plus Wave 9 / P1).
+ *
+ * A thin, typed HTTP client for the chipi-back `/v1/treasuries/:id/...`
+ * endpoints. It implements the same transport contract `@chipi-stack/chipi-react`
+ * injects into `useProposeAction` / `useTreasuryProposals` (`MultisigTransport`),
+ * so an integrator can wire `sdk.treasury.forTreasury(...)` straight into those
+ * hooks instead of hand-writing fetch glue.
+ *
+ * Auth model (decision §11.2 — owner-signature-as-authorization):
+ *   - propose / sign: `pk_` (the public api key) PLUS the owner's V2_SNIP12
+ *     envelope (already inside the proposal body) AND the owner's STARK
+ *     `ownerPubkey`. chipi-back's OwnerSignatureVerifier proves the request
+ *     came from a current on-chain owner, so no secret is needed — these are
+ *     safe to call from the browser.
+ *   - execute / list / allowance: `sk_` (a secret key bearer). execute relays
+ *     through the paymaster and meters; reads are org-private. Call these from
+ *     a server (a Next.js route handler / your backend), never the browser.
+ *
+ * The types below mirror `@chipi-stack/chipi-react/multisig`'s `TreasuryProposal`
+ * / `ProposeBody` field-for-field (post-#324: OE `executeAfter` is derived from
+ * `executeBefore`, never sent or stored). They're duplicated (not imported) so
+ * the server SDK never depends on the React package; TypeScript's structural
+ * typing makes a `TreasuryTransport` assignable to the hook's `MultisigTransport`.
+ */
+/** One owner's collected signature on a proposal. */
+interface TreasuryProposalSignature {
+    ownerId: number;
+    signerKind: string;
+    /** The owner's serialized inner V2_SNIP12 envelope (comma-joined felts). */
+    signature: string;
+}
+/** A treasury proposal as returned by the coordination backend. */
+interface TreasuryProposal {
+    id: string;
+    /** Set for generalized actions (vote / call any contract); null for payments. */
+    calls?: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[] | null;
+    /** Human label for an action ("Vote YES on Proposal #5"). */
+    title?: string | null;
+    /** Arbitrary integrator context. chipi-back has no column for it today, so
+     *  it is absent on every proposal it returns (kept for contract parity). */
+    meta?: Record<string, string | number> | null;
+    oeMessageHash: string;
+    oeNonce: string | null;
+    /** chipi-back persists only `oeExecuteBefore`; the OE `executeAfter` is
+     *  re-derived as `executeBefore - 2h` by executors (see chipi-react #324). */
+    oeExecuteBefore: string | null;
+    requiredApprovals: number;
+    status: "PROPOSED" | "APPROVED" | "EXECUTED" | "CANCELED" | "EXPIRED";
+    executedTxHash?: string | null;
+    signatures: TreasuryProposalSignature[];
+}
+/** The body the coordination backend's `propose` endpoint accepts. */
+interface ProposeBody {
+    proposerOwnerId: number;
+    recipient: string;
+    tokenAddress: string;
+    amount: string;
+    title: string;
+    calls: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[];
+    /** Arbitrary integrator context. NOTE: not persisted by chipi-back today
+     *  (no column) — the global ValidationPipe strips it. Kept for parity. */
+    meta?: Record<string, string | number>;
+    oeMessageHash: string;
+    oeNonce: string;
+    oeExecuteBefore: string;
+    requiredApprovals: number;
+    proposerSignature: string;
+    proposerSignerKind: string;
+}
+/** The approver's body for `sign` (mirrors chipi-react's call site). */
+interface ApproveBody {
+    ownerId: number;
+    signature: string;
+    signerKind: string;
+}
+/** Result of relaying an execute through the paymaster. */
+interface ExecuteResult {
+    executedTxHash?: string;
+    transactionHash?: string;
+}
+/** Free-execute meter for the org (shape owned by chipi-back's treasury svc). */
+interface MultisigAllowance {
+    freeExecutesRemaining?: number;
+    priceUsd?: number;
+    creditsUsd?: number;
+    canExecuteNow?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * A transport bound to one treasury + the local owner's STARK pubkey.
+ * Structurally compatible with `@chipi-stack/chipi-react`'s `MultisigTransport`.
+ */
+interface TreasuryTransport {
+    list(): Promise<{
+        items: TreasuryProposal[];
+    }>;
+    propose(body: ProposeBody): Promise<TreasuryProposal>;
+    sign(proposalId: string, body: ApproveBody): Promise<unknown>;
+    execute(proposalId: string, calldata: string[]): Promise<ExecuteResult>;
+    /** Read the org's free-execute meter (sk_). Not part of MultisigTransport. */
+    getMultisigAllowance(): Promise<MultisigAllowance>;
+}
+interface ForTreasuryConfig {
+    /** The org treasury id (the multisig wallet's row id in chipi-back). */
+    treasuryId: string;
+    /** The local owner's STARK public key (one 0x-hex felt). Sent with propose /
+     *  sign so the backend can verify the envelope commits to a current owner. */
+    ownerPubkey: string;
+    /** A secret key (`sk_`) for execute / list / allowance. Falls back to the
+     *  SDK's configured `apiSecretKey`. Required only for those three; propose /
+     *  sign authenticate with `pk_` + the owner signature. */
+    bearerToken?: string;
+}
+declare class ChipiTreasury {
+    private client;
+    private apiSecretKey?;
+    constructor(client: ChipiClient, apiSecretKey?: string | undefined);
+    private base;
+    /** Resolve a `sk_` for the secret-gated reads/execute, or fail loudly. */
+    private secret;
+    /**
+     * Build a {@link TreasuryTransport} for one treasury + owner. Wire the
+     * returned object directly into chipi-react's `useProposeAction` /
+     * `useTreasuryProposals` `transport` prop, or call its methods yourself.
+     */
+    forTreasury(config: ForTreasuryConfig): TreasuryTransport;
+}
+
 /**
  * PaymasterAdapter implementation that uses Chipi's backend API for gasless transactions.
  *
@@ -382,6 +519,7 @@ declare class ChipiSDK {
     readonly skus: ChipiSkus;
     readonly sessions: ChipiSessions;
     readonly exchanges: ChipiExchanges;
+    readonly treasury: ChipiTreasury;
     constructor(config: ChipiSDKConfig);
     /**
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -481,7 +619,7 @@ declare class ChipiSDK {
      * });
      * ```
      */
-    signTypedData({ params, }: {
+    signTypedData({ params }: {
         params: SignTypedDataParams;
     }): Promise<SignTypedDataResult>;
     /**
@@ -1142,6 +1280,51 @@ declare function buildEd25519Envelope(params: {
      */
     ownerIndex?: bigint;
 }): Promise<bigint[]>;
+/**
+ * Build a V2_SNIP12 Ed25519 envelope from an **externally-produced**
+ * signature — the Phantom / Solana flow. Phantom (and every external
+ * Ed25519 wallet) never exposes the private key: the user signs via
+ * `window.solana.signMessage(...)`, which returns a 64-byte signature
+ * (R‖s). This is the from-signature counterpart of
+ * `buildEd25519Envelope`, mirroring `buildEip191EnvelopeFromSignature`
+ * for MetaMask.
+ *
+ * IMPORTANT — what the wallet MUST sign:
+ *   The wallet must sign the EXACT bytes returned by
+ *   `ed25519SignedBytes(messageHash)` — the 64-byte hex-ASCII encoding
+ *   of the SNIP-12 OE hash — NOT the raw 32-byte `messageHash`. The
+ *   Cairo verifier reconstructs those same bytes from `messageHash`, so
+ *   a mismatch fails on chain. The dashboard adapter does:
+ *     await window.solana.connect();
+ *     // Phantom returns the 32-byte Ed25519 pubkey as a Solana PublicKey;
+ *     // `.toBytes()` is the Uint8Array this API expects.
+ *     const publicKey = window.solana.publicKey.toBytes();
+ *     const msg = ed25519SignedBytes(messageHash);
+ *     // Phantom's signMessage returns { signature: Uint8Array (64B), publicKey }.
+ *     const { signature } = await window.solana.signMessage(msg);
+ *     const env = await buildEd25519EnvelopeFromSignature({
+ *       signature, publicKey, messageHash,
+ *     });
+ *
+ * Async (unlike the synchronous EIP-191 from-signature path): the
+ * Garaga WASM hint builder must be initialized to produce the EC hints
+ * the Cairo Ed25519 verifier needs. The issue sketch (#311) showed a
+ * sync return; Ed25519 cannot avoid the WASM init that secp256k1 does.
+ */
+declare function buildEd25519EnvelopeFromSignature(params: {
+    /** 64-byte Ed25519 signature R(32)‖s(32) from the wallet's signMessage. */
+    signature: Uint8Array;
+    /** 32-byte Ed25519 public key (as Phantom returns it). */
+    publicKey: Uint8Array;
+    /** SNIP-12 hash of the OutsideExecution — see oe.ts::computeOeHash. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * MUST fit in u32. Same semantics + footgun as `buildEd25519Envelope`:
+     * pass the INDEX, never an `ed25519OwnerId` commitment.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
 
 /**
  * EIP-191 secp256k1 signer for SHHH V8.4 ShhhAccount.
@@ -2203,4 +2386,4 @@ declare function executeShhhSponsoredRaw(params: {
     chainId?: bigint | string;
 }): Promise<string>;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };