@naculus/connect-appkit-core 0.2.4 → 0.2.6

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, SessionKeyScope, ScopeCheckResult } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -362,6 +362,13 @@ declare function createDecimalsCache(token: TokenIdentity, known?: number): Deci
 declare function readDecimals(cache: DecimalsCache, token: TokenIdentity, known?: number): number | undefined;
 declare function writeDecimals(cache: DecimalsCache, token: TokenIdentity, value: number): void;
 
+/** Encode ERC-20 transfer(address,uint256), without signing or broadcasting. */
+declare function encodeErc20Transfer(to: string, amount: bigint): `0x${string}`;
+/** Encode ERC-20 approve(address,uint256), without signing or broadcasting. */
+declare function encodeErc20Approve(spender: string, amount: bigint): `0x${string}`;
+/** Encode ERC-20 transferFrom(address,address,uint256), without signing or broadcasting. */
+declare function encodeErc20TransferFrom(from: string, to: string, amount: bigint): `0x${string}`;
+
 /**
  * Normalize an EIP-1193 provider error into a WalletError.
  *
@@ -407,6 +414,44 @@ declare function decodeRevertReason(data: unknown): string | undefined;
 /** Decoded reason if available, otherwise the node's own message. */
 declare function resolveRevertReason(data: unknown, fallbackMessage: string): string;
 
+/** Resolve a simulation target without ever guessing a default chain. */
+declare function resolveSimulationEndpoint(requestedChainId: number | undefined, fallbackChainId: number | undefined, requestedRpcUrl?: string, fallbackRpcUrl?: string): {
+    chainId: number;
+    rpcUrl: string | undefined;
+};
+/** Resolve the chain from an explicit override or CAIP-2 chain context. */
+declare function resolveContextSimulationEndpoint(requestedChainId: number | undefined, currentChain: WalletChain | null | undefined): {
+    chainId: number;
+    rpcUrl: string | undefined;
+};
+
+interface SimulationTransaction {
+    to: string;
+    value?: string;
+    data?: string;
+    gas?: string;
+}
+interface SimulationCallClient {
+    chain?: {
+        id: number;
+    };
+    call(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        value: bigint;
+        from?: `0x${string}`;
+    }): Promise<unknown>;
+}
+interface TransactionSimulationContext {
+    chainId?: number;
+    currentChain?: WalletChain | null;
+    publicClient?: SimulationCallClient | null;
+    evmAccount?: string | null;
+    fetcher?: typeof fetch;
+}
+/** Basic revert check only: never claims asset changes or risk coverage. */
+declare function simulateTransactionPreview(tx: SimulationTransaction | undefined, context: TransactionSimulationContext): Promise<SimulationResult>;
+
 /**
  * Shared NameResolver instance for the name-resolution hooks.
  *
@@ -425,6 +470,315 @@ declare function getResolver(config?: NameResolverConfig): NameResolver;
 /** Test seam: drop the shared instance. */
 declare function __resetResolverForTests(): void;
 
+/** Framework-neutral in-app notification actions and settings persistence. */
+
+interface NotificationSettingsStorage {
+    getItem<T>(key: string): Promise<T | null>;
+    setItem<T>(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare const NOTIFICATION_SETTINGS_KEY = "naculus_notif_react_settings";
+declare const DEFAULT_NOTIFICATION_SETTINGS: NotificationSettings;
+/** Preserve the existing localStorage adapter and fail-open UI fallback. */
+declare function createNotificationSettingsStorage(): NotificationSettingsStorage;
+declare function loadNotificationSettings(storage: NotificationSettingsStorage): Promise<NotificationSettings | null>;
+declare function saveNotificationSettings(storage: NotificationSettingsStorage, settings: NotificationSettings): void;
+declare function updateNotificationSettings(current: NotificationSettings, update: Partial<NotificationSettings>): NotificationSettings;
+declare function channelsUpdate(channels: string[]): Partial<NotificationSettings>;
+declare function mutedChainSettings(settings: NotificationSettings, chainId: string, muted: boolean): Partial<NotificationSettings>;
+declare function createNotification(item: Omit<NotificationItem, "id" | "timestamp">): NotificationItem;
+declare function addInAppNotification(channel: InAppChannel, item: Omit<NotificationItem, "id" | "timestamp">): void;
+/** InAppChannel has no remove-one method; preserve its clear/replay behavior. */
+declare function clearOneInAppNotification(channel: InAppChannel, id: string): Promise<NotificationItem[]>;
+
+/**
+ * Destination-address checks shared by the React hook and the Vue composable.
+ *
+ * Syntactic only. `"ok"` means none of these checks found anything wrong —
+ * not that the recipient is who the user thinks. This cannot see an
+ * address-poisoning lookalike, a contract that will not release the funds,
+ * or a known-malicious destination. Labelling that "safe" once put a green
+ * tick beside a scammer's address; the level is deliberately not "safe".
+ */
+type AddressValidationLevel = "ok" | "warning" | "blocked";
+/** Machine-readable reason; the framework layer maps it to a user string. */
+type DestinationIssue = "empty" | "invalid_format" | "zero_address" | "burn_address";
+interface DestinationValidation {
+    isValid: boolean;
+    level: AddressValidationLevel;
+    issue: DestinationIssue | null;
+}
+/**
+ * Burn heuristic kept from the React hook: known sinks plus any well-formed
+ * address containing "dead". Stricter than connect-core's prefix-only
+ * `isBurnAddress`; unifying the two is a connect-lib change.
+ */
+declare function isBurnDestination(address: string): boolean;
+declare function validateDestination(address: string): DestinationValidation;
+/**
+ * The bare `0x…` account from either a CAIP-10 id (`eip155:1:0x…`) or a plain
+ * hex address; null when it is neither. Hooks and composables should not each
+ * carry their own copy of this split.
+ */
+declare function bareEvmAddress(account: string | null | undefined): `0x${string}` | null;
+
+/**
+ * Chain-abstraction (routing) domain types and the few decisions the React
+ * hooks and Vue composables share. The hooks inject the actual quote /
+ * compare / execute functions; nothing here talks to a network.
+ */
+interface RouteQuote {
+    routeId: string;
+    provider: string;
+    netReceiveFormatted: string;
+    toTokenSymbol: string;
+}
+interface RouteQuoteOptions {
+    sortBy?: "cost" | "time" | "balance";
+    maxSlippage?: number;
+}
+interface RouteQuoteInput {
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken?: string;
+    amount: string;
+    options?: RouteQuoteOptions;
+}
+type GetRouteQuotes = (from: string, to: string, token: string, amount: string, options?: RouteQuoteOptions, toToken?: string) => Promise<RouteQuote[]>;
+/**
+ * `BigInt()` throws on anything that is not a decimal integer — "1.5", "abc",
+ * "1e18" — so a user typing into an amount field must not reach it. Only a
+ * positive base-unit integer is a quotable amount.
+ */
+declare function isPositiveIntegerAmount(amount: string): boolean;
+/** True when every field a quote needs is present and the amount is quotable. */
+declare function isQuotableInput(input: RouteQuoteInput): boolean;
+interface CostComparison {
+    chain: string;
+    chainName: string;
+    totalCost: string;
+    gasCost: string;
+    estimatedTimeMs: number;
+}
+type CostComparisonOperation = "send_erc20" | "swap" | "bridge" | (string & {});
+interface CostComparisonOptions {
+    amount?: string;
+    token?: string;
+    [key: string]: unknown;
+}
+interface CompareCostsInput {
+    operation: CostComparisonOperation;
+    chains: string[];
+    options?: CostComparisonOptions;
+}
+type CompareCosts = (operation: string, chains: string[], options?: CostComparisonOptions) => Promise<CostComparison[]>;
+/**
+ * Value key for a compare-costs input. `chains` is an array and `options` an
+ * object; keying on identity re-fired the fetch on every render/reactive tick
+ * for a caller writing the natural inline literal — an unbounded loop against
+ * a cost API.
+ */
+declare function compareCostsKey(input: CompareCostsInput): string;
+interface ExecutableQuote {
+    routeId: string;
+    provider: string;
+    totalCost?: bigint;
+    estimatedTimeMs?: number;
+    toChain?: string;
+}
+interface ExecuteRouteResult {
+    fromTxHash: string;
+    toTxHash?: string;
+}
+interface ExecuteRouteOptions {
+    timeoutMs?: number;
+    gasLimit?: bigint;
+}
+interface ExecuteRouteError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: ExecuteRouteOptions) => Promise<ExecuteRouteResult>;
+/**
+ * Recipient check before a cross-chain execution. An empty recipient is wrong
+ * on every chain. Beyond that the destination namespace decides: when the
+ * quote names `toChain`, the address is validated for that namespace; when it
+ * does not, this returns null and the executor decides, rather than rejecting
+ * a valid non-EVM address on a guess.
+ */
+declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
+/** Normalise whatever an executor threw into the hook's error shape. */
+declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
+
+/** The subset of the config that changes what a key may spend or how it is sealed. */
+declare function sessionKeyConfigFingerprint(config?: SessionKeyManagerConfig): string;
+declare function getSharedSessionKeyManager(config?: SessionKeyManagerConfig): SessionKeyManager;
+/** Drop the shared instance. For tests and for a full sign-out that must forget keys. */
+declare function resetSharedSessionKeyManager(): void;
+
+/**
+ * Validation of an ERC-4337 `eth_getUserOperationReceipt` result, shared by
+ * the React hook and the Vue composable. A bundler is an untrusted party:
+ * every field is checked, the hash must match the one asked for, and a
+ * malformed receipt is refused instead of banked as a confirmation.
+ */
+declare class InvalidUserOperationReceiptError extends Error {
+    constructor(message: string);
+}
+declare function parseUserOperationReceipt(value: unknown, expectedHash: Hex): UserOperationReceipt;
+/**
+ * One `eth_getUserOperationReceipt` call. Resolves to the validated receipt,
+ * or null while the operation is not yet included. HTTP and JSON-RPC
+ * failures throw a plain Error (retryable); a malformed receipt throws
+ * InvalidUserOperationReceiptError (not retryable — the bundler is lying).
+ */
+declare function fetchUserOperationReceipt(bundlerUrl: string, hash: Hex, signal?: AbortSignal): Promise<UserOperationReceipt | null>;
+
+/**
+ * The decisions the smart-account hooks share, kept out of both framework
+ * shells: which chain a UserOperation targets, how the account config is
+ * assembled from options, and what a wallet's signature must look like.
+ */
+type SmartAccountType = "simple" | "light" | "kernel" | "safe";
+interface SmartAccountOptionsLike {
+    chainId?: string;
+    entryPoint?: Address;
+    accountType?: SmartAccountType;
+    salt?: bigint;
+}
+/**
+ * Target chain for a UserOperation. Fails closed: no chain → error rather
+ * than mainnet; a connected wallet on a different chain → chain_mismatch,
+ * because the signature it would produce is for the wrong domain.
+ */
+declare function resolveUserOpChain(optionsChainId: string | undefined, connectedChainId: string | null | undefined): string;
+/** Account config from owner, CAIP-2 chain and options; entry point falls back per chain. */
+declare function buildSmartAccountConfig(owner: Address, chainId: string, options?: SmartAccountOptionsLike): SmartAccountConfig;
+/** A wallet's answer to a signing request must be non-empty even-length hex. */
+declare function assertHexSignature(value: unknown): Hex;
+
+/**
+ * Signed off-chain delegation policies: the complete product flow, shared by
+ * React and Vue. Everything that decides whether a policy may be created,
+ * is still valid, or may sign or broadcast lives here; the framework shells
+ * only add state and wiring.
+ *
+ * Only `offchain` mode is created. An EIP-7702 or AA-module policy needs a
+ * real on-chain executor; accepting those here would turn a local record into
+ * a false delegation claim.
+ */
+/** What the execution planner says about a batch, plus the route it chose. */
+interface PolicyExecutionPreview extends ExecutionPlan {
+    route: string | null;
+}
+interface DelegationPolicyPreview {
+    policy: SessionKeyInfo | null;
+    scope: ScopeCheckResult;
+    execution: PolicyExecutionPreview;
+    signerMatches: boolean;
+    authorizationVerified: boolean;
+    ready: boolean;
+    broadcastReady: boolean;
+    broadcastRoute: PolicyExecutionRoute | null;
+    onchainAuthorizationVerified: boolean;
+    broadcastSponsored: boolean | null;
+    broadcastPromptless: boolean;
+    reason: string;
+}
+type PolicyExecutionRoute = "erc4337" | "eip7702";
+interface PolicyExecutionCheck {
+    ready: boolean;
+    authorizationInstalled: boolean;
+    sponsored: boolean;
+    promptless: boolean;
+    executorAddress?: `0x${string}`;
+    reason: string;
+}
+interface PreparedPolicyExecution {
+    digest: Hex;
+    transaction: SessionKeyTransaction;
+    payload: unknown;
+}
+interface PolicyExecutionSubmission {
+    route: PolicyExecutionRoute;
+    hash: Hex;
+    status: "submitted";
+}
+interface PolicyExecutionAdapter {
+    route: PolicyExecutionRoute;
+    check: (request: {
+        policy: SessionKeyInfo;
+        transaction: SessionKeyTransaction;
+    }) => Promise<PolicyExecutionCheck>;
+    prepare: (request: {
+        policy: SessionKeyInfo;
+        transaction: SessionKeyTransaction;
+    }) => Promise<PreparedPolicyExecution>;
+    broadcast: (request: {
+        policy: SessionKeyInfo;
+        prepared: PreparedPolicyExecution;
+        signature: Hex;
+    }) => Promise<PolicyExecutionSubmission>;
+}
+/** Recovers the signer of an EIP-191 message and compares; the flow never trusts a signature unrecovered. */
+type PolicySignatureVerifier = (input: {
+    message: string;
+    signature: `0x${string}`;
+    signerAddress: `0x${string}`;
+}) => Promise<boolean> | boolean;
+interface DelegationPolicyDeps {
+    manager: SessionKeyManager;
+    /** Origin bound into the signed message. */
+    origin: string;
+    /** Connected EOA, bare 0x form, or null. Read at call time. */
+    signer: () => `0x${string}` | null;
+    signMessage: (message: string) => Promise<string>;
+    verifySignature: PolicySignatureVerifier;
+    previewExecution: (callCount: number, atomicity: AtomicityRequirement) => PolicyExecutionPreview;
+    /** Whether gas must be sponsored for a broadcast to count as ready. */
+    sponsorship?: AtomicityRequirement;
+    adapter?: PolicyExecutionAdapter;
+    /** Current on-chain EIP-7702 delegation of the account. Read at call time. */
+    delegation: () => {
+        delegated: boolean | null;
+        delegate: `0x${string}` | null;
+    };
+    /** A host-provided encryption key is required for persistent policies. */
+    encryptionKeyConfigured: boolean;
+    storageAvailable: () => boolean;
+    /** Re-read the policy list after a mutation. */
+    refresh: () => Promise<void>;
+}
+/**
+ * True when the adapter's prepared transaction still means what was
+ * requested. Fail-closed: a field the caller left undefined is not a
+ * wildcard. An adapter may not add a target to a creation, add calldata to
+ * a plain transfer, or pick a chain the caller did not name — each of those
+ * changes what the session key ends up signing. Only "no value" and "0"
+ * (and "no data" and "0x") are treated as the same thing.
+ */
+declare function sameExecutionIntent(requested: SessionKeyTransaction, prepared: SessionKeyTransaction): boolean;
+/**
+ * The exact, deterministic message the main wallet signs. Every scope field
+ * is included in canonical order so a stored policy whose scope, signer or
+ * origin was altered no longer verifies. There must be exactly one copy of
+ * this function.
+ */
+declare function buildDelegationPolicyMessage(policy: SessionKeyInfo, origin: string): string;
+/** A stored policy is a verification candidate only in this state. */
+declare function isVerifiablePolicy(policy: SessionKeyInfo): boolean;
+interface DelegationPolicyFlow {
+    verifyStoredPolicy: (policy: SessionKeyInfo) => Promise<boolean>;
+    createPolicy: (scope: Partial<SessionKeyScope>) => Promise<SessionKeyInfo>;
+    revokePolicy: (policyId: string) => Promise<void>;
+    previewPolicyExecution: (policyId: string, tx: SessionKeyTransaction, callCount?: number, atomicity?: AtomicityRequirement) => Promise<DelegationPolicyPreview>;
+    signPolicyDigest: (policyId: string, digest: `0x${string}`, tx: SessionKeyTransaction) => Promise<`0x${string}`>;
+    executePolicy: (policyId: string, tx: SessionKeyTransaction) => Promise<PolicyExecutionSubmission>;
+}
+declare function createDelegationPolicyFlow(deps: DelegationPolicyDeps): DelegationPolicyFlow;
+
 declare function withTimeout<T>(promise: Promise<T>, ms: number, label?: string): Promise<T>;
 interface RetryOptions {
     maxRetries: number;
@@ -465,4 +819,36 @@ type Web3Action = {
 declare const initialWeb3State: Web3State;
 declare function web3Reducer(state: Web3State, action: Web3Action): Web3State;
 
-export { type AtomicSupport, type ChainCapabilities, type ChainInfo, type ConnectionStatus, type DecimalsCache, type RetryOptions, type SolanaIdentity, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, atomicSupportFor, chainNamespace, chainNumber, chainsForNamespace, createDecimalsCache, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isEvmChainId, normalizeCapabilities, normalizeEip155ChainId, readDecimals, readSolanaRoles, resolveChain, resolveEvmChainId, resolveRevertReason, selectChainCapabilities, toChainSwitchError, toEip155Accounts, toViemChain, tokenChainMismatch, tokenKey, web3Reducer, withRetry, withTimeout, writeDecimals };
+interface SiwxLocation {
+    host: string;
+    origin: string;
+}
+interface SiwxMessageLike {
+    chainId: string;
+    address: string;
+    domain: string;
+    issuedAt?: string | null;
+    expirationTime?: string | null;
+    notBefore?: string | null;
+}
+interface SiwxResultLike<M extends SiwxMessageLike = SiwxMessageLike> {
+    message: M;
+    signature: string;
+}
+declare function defaultSiwxDomain(location?: SiwxLocation): string;
+declare function defaultSiwxUri(location?: SiwxLocation): string;
+declare function isSiwxExpired(result: SiwxResultLike, now: Date): boolean;
+declare function isSiwxNotBeforeValid(result: SiwxResultLike, now: Date): boolean;
+declare function siwxResultToSession<M extends SiwxMessageLike>(result: SiwxResultLike<M>, now?: Date): {
+    id: string;
+    chainId: string;
+    address: string;
+    domain: string;
+    message: M;
+    signature: string;
+    issuedAt: string;
+    expiresAt: string | null;
+    refreshedAt: null;
+};
+
+export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type TransactionSimulationContext, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeChain, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, fetchUserOperationReceipt, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readDecimals, readSolanaRoles, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };