@usesigil/kit 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Anchor CPI event log parser for Sigil.
+ *
+ * Parses "Program data: " log lines from transaction logs to extract
+ * Anchor events. Uses the IDL-provided event discriminators (first 8 bytes
+ * of SHA256 of "event:<EventName>").
+ *
+ * The discriminator map is auto-generated by codama.mjs from the IDL.
+ * Run `pnpm run codama` after any Rust event changes.
+ */
+import { EVENT_DISCRIMINATOR_MAP } from "./generated/event-discriminators.js";
+/** All known Sigil event names */
+export type SigilEventName = (typeof EVENT_DISCRIMINATOR_MAP)[string];
+/** Parsed event from transaction logs */
+export interface SigilEvent {
+    /** Event name (e.g. "VaultCreated", "ActionAuthorized") */
+    name: SigilEventName;
+    /** Raw event data bytes (after discriminator) */
+    data: Uint8Array;
+}
+/**
+ * Parse Sigil Anchor events from transaction logs.
+ *
+ * Anchor emits events as "Program data: <base64>" log lines.
+ * The first 8 bytes are the event discriminator (SHA256 prefix).
+ *
+ * @param logs - Array of log strings from a transaction
+ * @returns Array of parsed events with name and raw data
+ */
+export declare function parseSigilEvents(logs: string[]): SigilEvent[];
+/**
+ * Extract events of a specific type from transaction logs.
+ */
+export declare function filterEvents(logs: string[], eventName: SigilEventName): SigilEvent[];
+/** Get all known event names */
+export declare function getEventNames(): SigilEventName[];
+/** Decoded event with typed fields */
+export interface DecodedSigilEvent {
+    name: SigilEventName;
+    /** Raw bytes preserved for debugging */
+    data: Uint8Array;
+    /** Decoded fields, or null if decoding fails */
+    fields: Record<string, unknown> | null;
+}
+/**
+ * Decode a parsed Sigil event's raw bytes into typed fields.
+ *
+ * Returns `fields: null` if the event name is unknown or decoding fails
+ * (e.g. events from older program versions with different layouts).
+ */
+export declare function decodeSigilEvent(event: SigilEvent): DecodedSigilEvent;
+/**
+ * Parse and decode Sigil events from transaction logs in one step.
+ */
+export declare function parseAndDecodeSigilEvents(logs: string[]): DecodedSigilEvent[];
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAmC9E,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,cAAc,CAAC;IACrB,iDAAiD;IACjD,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAgC7D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,cAAc,GACxB,UAAU,EAAE,CAEd;AAED,gCAAgC;AAChC,wBAAgB,aAAa,IAAI,cAAc,EAAE,CAEhD;AA8ED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,wCAAwC;IACxC,IAAI,EAAE,UAAU,CAAC;IACjB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,CAWrE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAE7E"}

package/dist/events.js

@@ -0,0 +1,151 @@
+/**
+ * Anchor CPI event log parser for Sigil.
+ *
+ * Parses "Program data: " log lines from transaction logs to extract
+ * Anchor events. Uses the IDL-provided event discriminators (first 8 bytes
+ * of SHA256 of "event:<EventName>").
+ *
+ * The discriminator map is auto-generated by codama.mjs from the IDL.
+ * Run `pnpm run codama` after any Rust event changes.
+ */
+import { EVENT_DISCRIMINATOR_MAP } from "./generated/event-discriminators.js";
+import { getActionAuthorizedDecoder, getSessionFinalizedDecoder, getFeesCollectedDecoder, getFundsDepositedDecoder, getFundsWithdrawnDecoder, getAgentTransferExecutedDecoder, getVaultCreatedDecoder, getVaultFrozenDecoder, getVaultReactivatedDecoder, getVaultClosedDecoder, getAgentRegisteredDecoder, getAgentRevokedDecoder, getAgentPausedEventDecoder, getAgentUnpausedEventDecoder, getAgentPermissionsUpdatedDecoder, getAgentSpendLimitCheckedDecoder, getEscrowCreatedDecoder, getEscrowSettledDecoder, getEscrowRefundedDecoder, getPolicyUpdatedDecoder, getPolicyChangeQueuedDecoder, getPolicyChangeAppliedDecoder, getPolicyChangeCancelledDecoder, getConstraintsChangeQueuedDecoder, getConstraintsChangeAppliedDecoder, getConstraintsChangeCancelledDecoder, getInstructionConstraintsCreatedDecoder, getInstructionConstraintsUpdatedDecoder, getInstructionConstraintsClosedDecoder, getDelegationRevokedDecoder, getPositionsSyncedDecoder, } from "./generated/types/index.js";
+/**
+ * Parse Sigil Anchor events from transaction logs.
+ *
+ * Anchor emits events as "Program data: <base64>" log lines.
+ * The first 8 bytes are the event discriminator (SHA256 prefix).
+ *
+ * @param logs - Array of log strings from a transaction
+ * @returns Array of parsed events with name and raw data
+ */
+export function parseSigilEvents(logs) {
+    const events = [];
+    const PROGRAM_DATA_PREFIX = "Program data: ";
+    for (const log of logs) {
+        if (!log.includes(PROGRAM_DATA_PREFIX))
+            continue;
+        const dataStart = log.indexOf(PROGRAM_DATA_PREFIX);
+        if (dataStart === -1)
+            continue;
+        const base64Data = log.slice(dataStart + PROGRAM_DATA_PREFIX.length);
+        try {
+            const bytes = base64ToBytes(base64Data);
+            if (bytes.length < 8)
+                continue;
+            // First 8 bytes = discriminator
+            const discHex = bytesToHex(bytes.slice(0, 8));
+            const eventName = EVENT_DISCRIMINATOR_MAP[discHex];
+            if (eventName) {
+                events.push({
+                    name: eventName,
+                    data: bytes.slice(8),
+                });
+            }
+        }
+        catch {
+            // Skip unparseable log lines
+        }
+    }
+    return events;
+}
+/**
+ * Extract events of a specific type from transaction logs.
+ */
+export function filterEvents(logs, eventName) {
+    return parseSigilEvents(logs).filter((e) => e.name === eventName);
+}
+/** Get all known event names */
+export function getEventNames() {
+    return Object.values(EVENT_DISCRIMINATOR_MAP);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function base64ToBytes(base64) {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ─── Event Decoder Map ──────────────────────────────────────────────────────
+// Decoders cached at module level — avoids re-creating struct decoders on every call
+const EVENT_DECODER_MAP = {
+    ActionAuthorized: getActionAuthorizedDecoder(),
+    SessionFinalized: getSessionFinalizedDecoder(),
+    FeesCollected: getFeesCollectedDecoder(),
+    FundsDeposited: getFundsDepositedDecoder(),
+    FundsWithdrawn: getFundsWithdrawnDecoder(),
+    AgentTransferExecuted: getAgentTransferExecutedDecoder(),
+    VaultCreated: getVaultCreatedDecoder(),
+    VaultFrozen: getVaultFrozenDecoder(),
+    VaultReactivated: getVaultReactivatedDecoder(),
+    VaultClosed: getVaultClosedDecoder(),
+    AgentRegistered: getAgentRegisteredDecoder(),
+    AgentRevoked: getAgentRevokedDecoder(),
+    AgentPausedEvent: getAgentPausedEventDecoder(),
+    AgentUnpausedEvent: getAgentUnpausedEventDecoder(),
+    AgentPermissionsUpdated: getAgentPermissionsUpdatedDecoder(),
+    AgentSpendLimitChecked: getAgentSpendLimitCheckedDecoder(),
+    EscrowCreated: getEscrowCreatedDecoder(),
+    EscrowSettled: getEscrowSettledDecoder(),
+    EscrowRefunded: getEscrowRefundedDecoder(),
+    PolicyUpdated: getPolicyUpdatedDecoder(),
+    PolicyChangeQueued: getPolicyChangeQueuedDecoder(),
+    PolicyChangeApplied: getPolicyChangeAppliedDecoder(),
+    PolicyChangeCancelled: getPolicyChangeCancelledDecoder(),
+    ConstraintsChangeQueued: getConstraintsChangeQueuedDecoder(),
+    ConstraintsChangeApplied: getConstraintsChangeAppliedDecoder(),
+    ConstraintsChangeCancelled: getConstraintsChangeCancelledDecoder(),
+    InstructionConstraintsCreated: getInstructionConstraintsCreatedDecoder(),
+    InstructionConstraintsUpdated: getInstructionConstraintsUpdatedDecoder(),
+    InstructionConstraintsClosed: getInstructionConstraintsClosedDecoder(),
+    DelegationRevoked: getDelegationRevokedDecoder(),
+    PositionsSynced: getPositionsSyncedDecoder(),
+};
+// Validate decoder map completeness at module init — catches drift when events are added/removed
+const discriminatorEventNames = new Set(Object.values(EVENT_DISCRIMINATOR_MAP));
+const decoderEventNames = new Set(Object.keys(EVENT_DECODER_MAP));
+for (const name of discriminatorEventNames) {
+    if (!decoderEventNames.has(name)) {
+        throw new Error(`EVENT_DECODER_MAP missing entry for "${name}". ` +
+            `Update EVENT_DECODER_MAP in events.ts after adding new events.`);
+    }
+}
+for (const name of decoderEventNames) {
+    if (!discriminatorEventNames.has(name)) {
+        throw new Error(`EVENT_DECODER_MAP has stale entry "${name}" not in EVENT_DISCRIMINATOR_MAP. ` +
+            `Remove it from EVENT_DECODER_MAP in events.ts.`);
+    }
+}
+/**
+ * Decode a parsed Sigil event's raw bytes into typed fields.
+ *
+ * Returns `fields: null` if the event name is unknown or decoding fails
+ * (e.g. events from older program versions with different layouts).
+ */
+export function decodeSigilEvent(event) {
+    const decoder = EVENT_DECODER_MAP[event.name];
+    if (!decoder) {
+        return { name: event.name, data: event.data, fields: null };
+    }
+    try {
+        const fields = decoder.decode(event.data);
+        return { name: event.name, data: event.data, fields };
+    }
+    catch {
+        return { name: event.name, data: event.data, fields: null };
+    }
+}
+/**
+ * Parse and decode Sigil events from transaction logs in one step.
+ */
+export function parseAndDecodeSigilEvents(logs) {
+    return parseSigilEvents(logs).map(decodeSigilEvent);
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/formatting.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Display formatting functions for USD, percentages, time, addresses, and token amounts.
+ *
+ * Design decisions:
+ * - All USD formatting takes bigint (6-decimal stablecoin base units) and converts to display.
+ * - Never use Number() on raw bigint amounts > 2^53 — precision loss. The division by 10^6
+ *   is safe because the result fits in Number range (< $18.4 trillion).
+ * - Locale: en-US hardcoded. International formatting is a future concern.
+ *
+ * This module is Phase 6 P0 from ANALYTICS-DATA-LAYER-PLAN, pulled forward into Step 5.5
+ * to eliminate overlap. Every other analytics module depends on these formatters.
+ */
+/**
+ * Format a stablecoin base-unit amount as a USD string.
+ *
+ * Default: full stablecoin precision (6 decimals). UI can truncate by passing decimals=2.
+ *
+ * @param amount - Raw amount in stablecoin base units (6 decimals). e.g., 500_000_000n = $500.000000
+ * @param decimals - Display decimal places (default 6 = full precision). Use 2 for display, 0 for KPI cards.
+ * @returns Formatted string like "$1,234.567890" (default) or "$1,234.57" (decimals=2)
+ */
+export declare function formatUsd(amount: bigint, decimals?: number): string;
+/**
+ * Format USD amount in compact notation for KPI cards and small spaces.
+ *
+ * @param amount - Raw amount in stablecoin base units (6 decimals)
+ * @returns Compact string like "$1.2K", "$3.5M", "$0.00"
+ */
+export declare function formatUsdCompact(amount: bigint): string;
+/**
+ * Format USD with explicit sign for P&L display.
+ *
+ * @param amount - Raw amount in stablecoin base units (can be negative for losses)
+ * @param decimals - Display decimal places (default 6 = full precision). Use 2 for display.
+ * @returns "+$234.560000" for gains, "-$89.120000" for losses, "$0.000000" for zero
+ */
+export declare function formatUsdSigned(amount: bigint, decimals?: number): string;
+/**
+ * Format a number as a percentage string.
+ *
+ * @param value - Percentage value (e.g., 24.7 for 24.7%)
+ * @param decimals - Decimal places (default 1)
+ * @returns "24.7%" or "0.0%"
+ */
+export declare function formatPercent(value: number, decimals?: number): string;
+/**
+ * Format percentage with explicit sign for P&L display.
+ *
+ * @param value - Percentage value (positive = gain, negative = loss)
+ * @returns "+24.7%" or "-5.2%" or "0.0%"
+ */
+export declare function formatPercentSigned(value: number, decimals?: number): string;
+/**
+ * Format a duration in seconds as a human-readable string.
+ *
+ * @param seconds - Duration in seconds (positive)
+ * @returns "2h 15m", "45m", "3d 12h", "< 1m"
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Format a Unix timestamp as a relative time string.
+ *
+ * @param timestamp - Unix timestamp in seconds
+ * @returns "just now", "2m ago", "3h ago", "2d ago"
+ */
+export declare function formatRelativeTime(timestamp: number): string;
+/**
+ * Format a Unix timestamp as time-until string.
+ *
+ * @param timestamp - Future Unix timestamp in seconds
+ * @returns "in 2h 15m", "in 45m", "expired"
+ */
+export declare function formatTimeUntil(timestamp: number): string;
+/**
+ * Truncate a Solana address for display.
+ *
+ * @param address - Full base58 address
+ * @param chars - Characters to show on each side (default 4)
+ * @returns "7Kp3...xQ2m"
+ */
+export declare function formatAddress(address: string, chars?: number): string;
+/**
+ * Format a token amount with symbol at full token precision.
+ *
+ * Default: full decimals for the token (6 for USDC, 9 for SOL). UI can truncate.
+ *
+ * @param amount - Raw amount in base units
+ * @param decimals - Token decimals (6 for USDC, 9 for SOL)
+ * @param symbol - Token symbol ("USDC", "SOL")
+ * @param displayDecimals - Override display precision (default: full token decimals)
+ * @returns "1,234.560000 USDC" or "0.123456789 SOL"
+ */
+export declare function formatTokenAmount(amount: bigint, decimals: number, symbol: string, displayDecimals?: number): string;
+/**
+ * Format token amount in compact notation.
+ *
+ * @param amount - Raw amount in base units
+ * @param decimals - Token decimals
+ * @param symbol - Token symbol
+ * @returns "1.2K USDC", "3.5M SOL"
+ */
+export declare function formatTokenAmountCompact(amount: bigint, decimals: number, symbol: string): string;
+//# sourceMappingURL=formatting.d.ts.map

package/dist/formatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../src/formatting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqDH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAsB9D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAIpE;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAMvE;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAetD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMzD;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,CAGhE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAkBR;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,MAAM,CAOR"}

package/dist/formatting.js

@@ -0,0 +1,244 @@
+/**
+ * Display formatting functions for USD, percentages, time, addresses, and token amounts.
+ *
+ * Design decisions:
+ * - All USD formatting takes bigint (6-decimal stablecoin base units) and converts to display.
+ * - Never use Number() on raw bigint amounts > 2^53 — precision loss. The division by 10^6
+ *   is safe because the result fits in Number range (< $18.4 trillion).
+ * - Locale: en-US hardcoded. International formatting is a future concern.
+ *
+ * This module is Phase 6 P0 from ANALYTICS-DATA-LAYER-PLAN, pulled forward into Step 5.5
+ * to eliminate overlap. Every other analytics module depends on these formatters.
+ */
+import { STABLECOIN_USD_FACTOR } from "./types.js";
+// ─── Cached Intl Formatters ─────────────────────────────────────────────────
+/** Full stablecoin precision (6 decimals = 1 micro-dollar). Default for SDK output. */
+const usdFormatter6 = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 6,
+    maximumFractionDigits: 6,
+});
+const usdFormatter2 = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+});
+const usdFormatter0 = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+});
+const usdFormatterCompact = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    notation: "compact",
+    maximumFractionDigits: 1,
+});
+const numberFormatter = new Intl.NumberFormat("en-US");
+const numberFormatterCompact = new Intl.NumberFormat("en-US", {
+    notation: "compact",
+    maximumFractionDigits: 1,
+});
+/** Convert stablecoin base units (6 decimals) to a Number in dollars. Safe for < $18.4T. */
+function usdToNumber(absAmount) {
+    return (Number(absAmount / STABLECOIN_USD_FACTOR) +
+        Number(absAmount % STABLECOIN_USD_FACTOR) / 1_000_000);
+}
+// ─── USD Formatting ──────────────────────────────────────────────────────────
+/**
+ * Format a stablecoin base-unit amount as a USD string.
+ *
+ * Default: full stablecoin precision (6 decimals). UI can truncate by passing decimals=2.
+ *
+ * @param amount - Raw amount in stablecoin base units (6 decimals). e.g., 500_000_000n = $500.000000
+ * @param decimals - Display decimal places (default 6 = full precision). Use 2 for display, 0 for KPI cards.
+ * @returns Formatted string like "$1,234.567890" (default) or "$1,234.57" (decimals=2)
+ */
+export function formatUsd(amount, decimals = 6) {
+    const isNegative = amount < 0n;
+    const absAmount = isNegative ? -amount : amount;
+    const dollarValue = usdToNumber(absAmount);
+    // Use cached formatter for common decimal counts, dynamic for others
+    const formatter = decimals === 6
+        ? usdFormatter6
+        : decimals === 2
+            ? usdFormatter2
+            : decimals === 0
+                ? usdFormatter0
+                : new Intl.NumberFormat("en-US", {
+                    style: "currency",
+                    currency: "USD",
+                    minimumFractionDigits: decimals,
+                    maximumFractionDigits: decimals,
+                });
+    const formatted = formatter.format(dollarValue);
+    return isNegative ? `-${formatted}` : formatted;
+}
+/**
+ * Format USD amount in compact notation for KPI cards and small spaces.
+ *
+ * @param amount - Raw amount in stablecoin base units (6 decimals)
+ * @returns Compact string like "$1.2K", "$3.5M", "$0.00"
+ */
+export function formatUsdCompact(amount) {
+    const isNegative = amount < 0n;
+    const absAmount = isNegative ? -amount : amount;
+    const dollarValue = usdToNumber(absAmount);
+    const formatted = usdFormatterCompact.format(dollarValue);
+    return isNegative ? `-${formatted}` : formatted;
+}
+/**
+ * Format USD with explicit sign for P&L display.
+ *
+ * @param amount - Raw amount in stablecoin base units (can be negative for losses)
+ * @param decimals - Display decimal places (default 6 = full precision). Use 2 for display.
+ * @returns "+$234.560000" for gains, "-$89.120000" for losses, "$0.000000" for zero
+ */
+export function formatUsdSigned(amount, decimals = 6) {
+    if (amount === 0n)
+        return formatUsd(0n, decimals);
+    if (amount > 0n)
+        return `+${formatUsd(amount, decimals)}`;
+    return formatUsd(amount, decimals); // formatUsd already handles negative
+}
+// ─── Percentage Formatting ───────────────────────────────────────────────────
+/**
+ * Format a number as a percentage string.
+ *
+ * @param value - Percentage value (e.g., 24.7 for 24.7%)
+ * @param decimals - Decimal places (default 1)
+ * @returns "24.7%" or "0.0%"
+ */
+export function formatPercent(value, decimals = 1) {
+    return `${value.toFixed(decimals)}%`;
+}
+/**
+ * Format percentage with explicit sign for P&L display.
+ *
+ * @param value - Percentage value (positive = gain, negative = loss)
+ * @returns "+24.7%" or "-5.2%" or "0.0%"
+ */
+export function formatPercentSigned(value, decimals = 1) {
+    // Scale threshold to match display precision: 0.05 for 1 dec, 0.005 for 2 dec, etc.
+    const threshold = 0.5 * Math.pow(10, -decimals);
+    if (Math.abs(value) < threshold)
+        return `0.${"0".repeat(decimals)}%`;
+    if (value > 0)
+        return `+${value.toFixed(decimals)}%`;
+    return `${value.toFixed(decimals)}%`;
+}
+// ─── Time Formatting ─────────────────────────────────────────────────────────
+/**
+ * Format a duration in seconds as a human-readable string.
+ *
+ * @param seconds - Duration in seconds (positive)
+ * @returns "2h 15m", "45m", "3d 12h", "< 1m"
+ */
+export function formatDuration(seconds) {
+    if (seconds < 0)
+        return "0m";
+    if (seconds < 60)
+        return "< 1m";
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    if (days > 0) {
+        return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+    }
+    if (hours > 0) {
+        return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+    }
+    return `${minutes}m`;
+}
+/**
+ * Format a Unix timestamp as a relative time string.
+ *
+ * @param timestamp - Unix timestamp in seconds
+ * @returns "just now", "2m ago", "3h ago", "2d ago"
+ */
+export function formatRelativeTime(timestamp) {
+    const now = Math.floor(Date.now() / 1000);
+    const diff = now - timestamp;
+    if (diff < 60)
+        return "just now";
+    if (diff < 3600)
+        return `${Math.floor(diff / 60)}m ago`;
+    if (diff < 86400)
+        return `${Math.floor(diff / 3600)}h ago`;
+    if (diff < 2592000)
+        return `${Math.floor(diff / 86400)}d ago`;
+    return `${Math.floor(diff / 2592000)}mo ago`;
+}
+/**
+ * Format a Unix timestamp as time-until string.
+ *
+ * @param timestamp - Future Unix timestamp in seconds
+ * @returns "in 2h 15m", "in 45m", "expired"
+ */
+export function formatTimeUntil(timestamp) {
+    const now = Math.floor(Date.now() / 1000);
+    const diff = timestamp - now;
+    if (diff <= 0)
+        return "expired";
+    return `in ${formatDuration(diff)}`;
+}
+// ─── Address Formatting ──────────────────────────────────────────────────────
+/**
+ * Truncate a Solana address for display.
+ *
+ * @param address - Full base58 address
+ * @param chars - Characters to show on each side (default 4)
+ * @returns "7Kp3...xQ2m"
+ */
+export function formatAddress(address, chars = 4) {
+    if (address.length <= chars * 2 + 3)
+        return address;
+    return `${address.slice(0, chars)}...${address.slice(-chars)}`;
+}
+// ─── Token Amount Formatting ─────────────────────────────────────────────────
+/**
+ * Format a token amount with symbol at full token precision.
+ *
+ * Default: full decimals for the token (6 for USDC, 9 for SOL). UI can truncate.
+ *
+ * @param amount - Raw amount in base units
+ * @param decimals - Token decimals (6 for USDC, 9 for SOL)
+ * @param symbol - Token symbol ("USDC", "SOL")
+ * @param displayDecimals - Override display precision (default: full token decimals)
+ * @returns "1,234.560000 USDC" or "0.123456789 SOL"
+ */
+export function formatTokenAmount(amount, decimals, symbol, displayDecimals) {
+    const isNegative = amount < 0n;
+    const absAmount = isNegative ? -amount : amount;
+    const factor = 10n ** BigInt(decimals);
+    const whole = absAmount / factor;
+    const frac = absAmount % factor;
+    const fracDigits = displayDecimals ?? decimals;
+    const fracStr = frac
+        .toString()
+        .padStart(decimals, "0")
+        .slice(0, fracDigits);
+    const wholeFormatted = numberFormatter.format(Number(whole));
+    const result = fracDigits > 0
+        ? `${wholeFormatted}.${fracStr} ${symbol}`
+        : `${wholeFormatted} ${symbol}`;
+    return isNegative ? `-${result}` : result;
+}
+/**
+ * Format token amount in compact notation.
+ *
+ * @param amount - Raw amount in base units
+ * @param decimals - Token decimals
+ * @param symbol - Token symbol
+ * @returns "1.2K USDC", "3.5M SOL"
+ */
+export function formatTokenAmountCompact(amount, decimals, symbol) {
+    const factor = 10n ** BigInt(decimals);
+    const value = Number(amount / factor) + Number(amount % factor) / Number(factor);
+    const formatted = numberFormatterCompact.format(value);
+    return `${formatted} ${symbol}`;
+}
+//# sourceMappingURL=formatting.js.map

package/dist/formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../src/formatting.ts"],"names":[],"mappings":"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"}

package/dist/generated/accounts/agentSpendOverlay.d.ts

@@ -0,0 +1,54 @@
+/**
+ * This code was AUTOGENERATED using the Codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun Codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+import { fetchEncodedAccount, fetchEncodedAccounts, type Account, type Address, type EncodedAccount, type FetchAccountConfig, type FetchAccountsConfig, type FixedSizeCodec, type FixedSizeDecoder, type FixedSizeEncoder, type MaybeAccount, type MaybeEncodedAccount, type ReadonlyUint8Array } from "@solana/kit";
+import { type AgentContributionEntry, type AgentContributionEntryArgs } from "../types/index.js";
+export declare const AGENT_SPEND_OVERLAY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare function getAgentSpendOverlayDiscriminatorBytes(): ReadonlyUint8Array<ArrayBuffer>;
+export type AgentSpendOverlay = {
+    discriminator: ReadonlyUint8Array;
+    /** Associated vault pubkey */
+    vault: Address;
+    /** Agent contribution entries (up to MAX_OVERLAY_ENTRIES agents) */
+    entries: Array<AgentContributionEntry>;
+    /** Bump seed for PDA */
+    bump: number;
+    /** Padding for 8-byte alignment */
+    padding: ReadonlyUint8Array;
+    /** Per-agent cumulative spend in USD base units */
+    lifetimeSpend: Array<bigint>;
+    /** Per-agent cumulative transaction count */
+    lifetimeTxCount: Array<bigint>;
+};
+export type AgentSpendOverlayArgs = {
+    /** Associated vault pubkey */
+    vault: Address;
+    /** Agent contribution entries (up to MAX_OVERLAY_ENTRIES agents) */
+    entries: Array<AgentContributionEntryArgs>;
+    /** Bump seed for PDA */
+    bump: number;
+    /** Padding for 8-byte alignment */
+    padding: ReadonlyUint8Array;
+    /** Per-agent cumulative spend in USD base units */
+    lifetimeSpend: Array<number | bigint>;
+    /** Per-agent cumulative transaction count */
+    lifetimeTxCount: Array<number | bigint>;
+};
+/** Gets the encoder for {@link AgentSpendOverlayArgs} account data. */
+export declare function getAgentSpendOverlayEncoder(): FixedSizeEncoder<AgentSpendOverlayArgs>;
+/** Gets the decoder for {@link AgentSpendOverlay} account data. */
+export declare function getAgentSpendOverlayDecoder(): FixedSizeDecoder<AgentSpendOverlay>;
+/** Gets the codec for {@link AgentSpendOverlay} account data. */
+export declare function getAgentSpendOverlayCodec(): FixedSizeCodec<AgentSpendOverlayArgs, AgentSpendOverlay>;
+export declare function decodeAgentSpendOverlay<TAddress extends string = string>(encodedAccount: EncodedAccount<TAddress>): Account<AgentSpendOverlay, TAddress>;
+export declare function decodeAgentSpendOverlay<TAddress extends string = string>(encodedAccount: MaybeEncodedAccount<TAddress>): MaybeAccount<AgentSpendOverlay, TAddress>;
+export declare function fetchAgentSpendOverlay<TAddress extends string = string>(rpc: Parameters<typeof fetchEncodedAccount>[0], address: Address<TAddress>, config?: FetchAccountConfig): Promise<Account<AgentSpendOverlay, TAddress>>;
+export declare function fetchMaybeAgentSpendOverlay<TAddress extends string = string>(rpc: Parameters<typeof fetchEncodedAccount>[0], address: Address<TAddress>, config?: FetchAccountConfig): Promise<MaybeAccount<AgentSpendOverlay, TAddress>>;
+export declare function fetchAllAgentSpendOverlay(rpc: Parameters<typeof fetchEncodedAccounts>[0], addresses: Array<Address>, config?: FetchAccountsConfig): Promise<Account<AgentSpendOverlay>[]>;
+export declare function fetchAllMaybeAgentSpendOverlay(rpc: Parameters<typeof fetchEncodedAccounts>[0], addresses: Array<Address>, config?: FetchAccountsConfig): Promise<MaybeAccount<AgentSpendOverlay>[]>;
+export declare function getAgentSpendOverlaySize(): number;
+//# sourceMappingURL=agentSpendOverlay.d.ts.map

package/dist/generated/accounts/agentSpendOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSpendOverlay.d.ts","sourceRoot":"","sources":["../../../src/generated/accounts/agentSpendOverlay.ts"],"names":[],"mappings":"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"}