kontext-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1320 @@
+/** Supported blockchain networks */
+type Chain = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'arc';
+/** Supported stablecoin tokens */
+type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC';
+/** SDK operating mode */
+type KontextMode = 'local' | 'cloud';
+/** Environment configuration */
+type Environment = 'development' | 'staging' | 'production';
+/** Anomaly severity levels */
+type AnomalySeverity = 'low' | 'medium' | 'high' | 'critical';
+/** Task status lifecycle */
+type TaskStatus = 'pending' | 'in_progress' | 'confirmed' | 'failed' | 'expired';
+/** Supported export formats */
+type ExportFormat = 'json' | 'csv';
+/** Report types */
+type ReportType = 'compliance' | 'transaction' | 'anomaly' | 'sar' | 'ctr';
+/** Anomaly detection rule types */
+type AnomalyRuleType = 'unusualAmount' | 'frequencySpike' | 'newDestination' | 'offHoursActivity' | 'rapidSuccession' | 'roundAmount';
+/** SDK initialization configuration */
+interface KontextConfig {
+    /** API key for cloud mode (optional for local/OSS mode) */
+    apiKey?: string;
+    /** Unique project identifier */
+    projectId: string;
+    /** Deployment environment */
+    environment: Environment;
+    /** Backend API URL (defaults to Kontext cloud) */
+    apiUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Batch size for log flushing */
+    batchSize?: number;
+    /** Batch flush interval in milliseconds */
+    flushIntervalMs?: number;
+    /** Local file output directory for OSS mode */
+    localOutputDir?: string;
+}
+/** Base action log entry */
+interface ActionLog {
+    /** Unique action identifier */
+    id: string;
+    /** Timestamp of the action */
+    timestamp: string;
+    /** ID of the project */
+    projectId: string;
+    /** ID of the agent performing the action */
+    agentId: string;
+    /** Correlation ID for tracing related actions */
+    correlationId: string;
+    /** Type of action */
+    type: string;
+    /** Human-readable description */
+    description: string;
+    /** Arbitrary metadata */
+    metadata: Record<string, unknown>;
+    /** Rolling SHA-256 digest for tamper-evident audit trail */
+    digest?: string;
+    /** Prior digest in the chain */
+    priorDigest?: string;
+}
+/** Input for logging a generic action */
+interface LogActionInput {
+    /** Type of action (e.g., 'transfer', 'approval', 'query') */
+    type: string;
+    /** Human-readable description */
+    description: string;
+    /** ID of the agent performing the action */
+    agentId: string;
+    /** Optional correlation ID (auto-generated if not provided) */
+    correlationId?: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for logging a cryptocurrency transaction */
+interface LogTransactionInput {
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Blockchain network */
+    chain: Chain;
+    /** Transaction amount (string to preserve decimal precision) */
+    amount: string;
+    /** Token being transferred */
+    token: Token;
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** ID of the agent initiating the transaction */
+    agentId: string;
+    /** Optional correlation ID */
+    correlationId?: string;
+    /** Additional transaction metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Stored transaction record */
+interface TransactionRecord extends ActionLog {
+    type: 'transaction';
+    txHash: string;
+    chain: Chain;
+    amount: string;
+    token: Token;
+    from: string;
+    to: string;
+}
+/** Input for creating a new tracked task */
+interface CreateTaskInput {
+    /** Human-readable task description */
+    description: string;
+    /** ID of the agent responsible for the task */
+    agentId: string;
+    /** List of evidence types required for confirmation */
+    requiredEvidence: string[];
+    /** Optional correlation ID */
+    correlationId?: string;
+    /** Task expiration time in milliseconds from creation */
+    expiresInMs?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Evidence provided for task confirmation */
+interface TaskEvidence {
+    /** On-chain transaction hash */
+    txHash?: string;
+    /** Transaction receipt data */
+    receipt?: Record<string, unknown>;
+    /** Proof data (e.g., Merkle proof, signature) */
+    proof?: string;
+    /** Any additional evidence fields */
+    [key: string]: unknown;
+}
+/** Input for confirming a task */
+interface ConfirmTaskInput {
+    /** ID of the task to confirm */
+    taskId: string;
+    /** Evidence supporting task completion */
+    evidence: TaskEvidence;
+}
+/** Complete task record */
+interface Task {
+    /** Unique task identifier */
+    id: string;
+    /** Project ID */
+    projectId: string;
+    /** Task description */
+    description: string;
+    /** Responsible agent ID */
+    agentId: string;
+    /** Current task status */
+    status: TaskStatus;
+    /** Required evidence types */
+    requiredEvidence: string[];
+    /** Provided evidence (if any) */
+    providedEvidence: TaskEvidence | null;
+    /** Correlation ID */
+    correlationId: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Confirmation timestamp */
+    confirmedAt: string | null;
+    /** Expiration timestamp */
+    expiresAt: string | null;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}
+/** Date range filter */
+interface DateRange {
+    /** Start date (inclusive) */
+    start: Date;
+    /** End date (inclusive) */
+    end: Date;
+}
+/** Export configuration */
+interface ExportOptions {
+    /** Output format */
+    format: ExportFormat;
+    /** Date range filter */
+    dateRange?: DateRange;
+    /** Filter by agent IDs */
+    agentIds?: string[];
+    /** Filter by action types */
+    types?: string[];
+    /** Filter by chains */
+    chains?: Chain[];
+    /** Include task data */
+    includeTasks?: boolean;
+    /** Include anomaly data */
+    includeAnomalies?: boolean;
+}
+/** Report generation options */
+interface ReportOptions {
+    /** Type of report */
+    type: ReportType;
+    /** Reporting period */
+    period: DateRange;
+    /** Filter by agent IDs */
+    agentIds?: string[];
+}
+/** Generated compliance report */
+interface ComplianceReport {
+    /** Report ID */
+    id: string;
+    /** Report type */
+    type: ReportType;
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Reporting period */
+    period: DateRange;
+    /** Project ID */
+    projectId: string;
+    /** Summary statistics */
+    summary: {
+        totalActions: number;
+        totalTransactions: number;
+        totalTasks: number;
+        confirmedTasks: number;
+        failedTasks: number;
+        totalAnomalies: number;
+        averageTrustScore: number;
+    };
+    /** Action logs in the period */
+    actions: ActionLog[];
+    /** Transaction records in the period */
+    transactions: TransactionRecord[];
+    /** Tasks in the period */
+    tasks: Task[];
+    /** Anomalies detected in the period */
+    anomalies: AnomalyEvent[];
+}
+/** Exported audit data */
+interface ExportResult {
+    /** Export format */
+    format: ExportFormat;
+    /** Export timestamp */
+    exportedAt: string;
+    /** Number of records */
+    recordCount: number;
+    /** The data (JSON string or CSV string) */
+    data: string;
+    /** Terminal digest of the chain at time of export */
+    terminalDigest?: string;
+}
+/** Subject information for SAR/CTR reports */
+interface ReportSubject {
+    /** Subject name or identifier */
+    name: string;
+    /** Agent ID (if applicable) */
+    agentId?: string;
+    /** Wallet addresses associated with the subject */
+    addresses: string[];
+    /** Additional identifying information */
+    identifiers?: Record<string, string>;
+}
+/** Suspicious Activity Report template */
+interface SARReport {
+    /** Report ID */
+    id: string;
+    /** Report type discriminator */
+    type: 'sar';
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Reporting period */
+    period: DateRange;
+    /** Project ID */
+    projectId: string;
+    /** Filing institution information */
+    filingInstitution: string;
+    /** Subject(s) of the report */
+    subjects: ReportSubject[];
+    /** Narrative summary of suspicious activity */
+    narrative: string;
+    /** Suspicious activity categories */
+    activityCategories: string[];
+    /** Total amount involved */
+    totalAmount: string;
+    /** Currency/token */
+    currency: string;
+    /** Transactions flagged as suspicious */
+    suspiciousTransactions: TransactionRecord[];
+    /** Related anomalies */
+    anomalies: AnomalyEvent[];
+    /** Supporting action logs */
+    supportingActions: ActionLog[];
+    /** Whether this is a continuing activity report */
+    isContinuingActivity: boolean;
+    /** Prior report ID if continuing */
+    priorReportId: string | null;
+    /** Status of the report */
+    status: 'draft' | 'review' | 'filed';
+}
+/** Currency Transaction Report template */
+interface CTRReport {
+    /** Report ID */
+    id: string;
+    /** Report type discriminator */
+    type: 'ctr';
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Reporting period */
+    period: DateRange;
+    /** Project ID */
+    projectId: string;
+    /** Filing institution information */
+    filingInstitution: string;
+    /** Person/entity conducting the transactions */
+    conductors: ReportSubject[];
+    /** Transactions included in the report */
+    transactions: TransactionRecord[];
+    /** Total cash-in amount */
+    totalCashIn: string;
+    /** Total cash-out amount */
+    totalCashOut: string;
+    /** Currency/token */
+    currency: string;
+    /** Whether multiple transactions are aggregated */
+    isAggregated: boolean;
+    /** Chains involved */
+    chainsInvolved: Chain[];
+    /** Supporting action logs */
+    supportingActions: ActionLog[];
+    /** Status of the report */
+    status: 'draft' | 'review' | 'filed';
+}
+/** Trust score result for an agent */
+interface TrustScore {
+    /** Agent ID */
+    agentId: string;
+    /** Overall trust score (0-100) */
+    score: number;
+    /** Score breakdown by factor */
+    factors: TrustFactor[];
+    /** Timestamp of computation */
+    computedAt: string;
+    /** Trust level label */
+    level: 'untrusted' | 'low' | 'medium' | 'high' | 'verified';
+}
+/** Individual trust factor */
+interface TrustFactor {
+    /** Factor name */
+    name: string;
+    /** Factor score (0-100) */
+    score: number;
+    /** Factor weight (0-1) */
+    weight: number;
+    /** Human-readable description */
+    description: string;
+}
+/** Transaction evaluation result */
+interface TransactionEvaluation {
+    /** Transaction hash */
+    txHash: string;
+    /** Risk score (0-100, higher = more risky) */
+    riskScore: number;
+    /** Risk level */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Individual risk factors */
+    factors: RiskFactor[];
+    /** Whether the transaction should be flagged */
+    flagged: boolean;
+    /** Recommended action */
+    recommendation: 'approve' | 'review' | 'block';
+    /** Evaluation timestamp */
+    evaluatedAt: string;
+}
+/** Individual risk factor */
+interface RiskFactor {
+    /** Factor name */
+    name: string;
+    /** Risk score contribution (0-100) */
+    score: number;
+    /** Human-readable description */
+    description: string;
+}
+/** Anomaly detection configuration */
+interface AnomalyDetectionConfig {
+    /** Detection rules to enable */
+    rules: AnomalyRuleType[];
+    /** Thresholds for detection */
+    thresholds?: AnomalyThresholds;
+}
+/** Configurable anomaly thresholds */
+interface AnomalyThresholds {
+    /** Maximum transaction amount before flagging */
+    maxAmount?: string;
+    /** Maximum transactions per hour */
+    maxFrequency?: number;
+    /** Hours considered "off-hours" (24h format, e.g., [22, 23, 0, 1, 2, 3, 4, 5]) */
+    offHours?: number[];
+    /** Minimum seconds between transactions before "rapid succession" flag */
+    minIntervalSeconds?: number;
+}
+/** Detected anomaly event */
+interface AnomalyEvent {
+    /** Unique anomaly ID */
+    id: string;
+    /** Anomaly type/rule that triggered */
+    type: AnomalyRuleType;
+    /** Severity level */
+    severity: AnomalySeverity;
+    /** Human-readable description */
+    description: string;
+    /** ID of the agent involved */
+    agentId: string;
+    /** Related action log ID */
+    actionId: string;
+    /** Detection timestamp */
+    detectedAt: string;
+    /** Related data */
+    data: Record<string, unknown>;
+    /** Whether the anomaly has been reviewed */
+    reviewed: boolean;
+}
+/** Anomaly event callback */
+type AnomalyCallback = (anomaly: AnomalyEvent) => void;
+/** USDC compliance check result */
+interface UsdcComplianceCheck {
+    /** Whether the transaction is compliant */
+    compliant: boolean;
+    /** List of compliance checks performed */
+    checks: ComplianceCheckResult[];
+    /** Overall risk level */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Recommendations */
+    recommendations: string[];
+}
+/** Individual compliance check result */
+interface ComplianceCheckResult {
+    /** Check name */
+    name: string;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Severity if failed */
+    severity: AnomalySeverity;
+}
+/** Error codes for Kontext SDK */
+declare enum KontextErrorCode {
+    INITIALIZATION_ERROR = "INITIALIZATION_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    TASK_NOT_FOUND = "TASK_NOT_FOUND",
+    TASK_ALREADY_CONFIRMED = "TASK_ALREADY_CONFIRMED",
+    TASK_EXPIRED = "TASK_EXPIRED",
+    INSUFFICIENT_EVIDENCE = "INSUFFICIENT_EVIDENCE",
+    API_ERROR = "API_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    EXPORT_ERROR = "EXPORT_ERROR",
+    ANOMALY_CONFIG_ERROR = "ANOMALY_CONFIG_ERROR"
+}
+/** Kontext SDK error */
+declare class KontextError extends Error {
+    readonly code: KontextErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: KontextErrorCode, message: string, details?: Record<string, unknown>);
+}
+
+/** Microsecond precision timestamp */
+interface PrecisionTimestamp {
+    /** ISO 8601 timestamp */
+    iso: string;
+    /** High-resolution time in nanoseconds (from process.hrtime.bigint) */
+    hrtime: bigint;
+    /** Microsecond component derived from hrtime */
+    microseconds: number;
+}
+/** A single link in the digest chain */
+interface DigestLink {
+    /** The computed SHA-256 digest for this event */
+    digest: string;
+    /** The prior digest (HD-1) */
+    priorDigest: string;
+    /** The salt derived from the timestamp */
+    salt: string;
+    /** The high-precision timestamp of this event */
+    timestamp: PrecisionTimestamp;
+    /** Sequence number in the chain (0-indexed) */
+    sequence: number;
+    /** The action ID this digest covers */
+    actionId: string;
+}
+/** Result of verifying a digest chain */
+interface DigestVerification {
+    /** Whether the entire chain is valid */
+    valid: boolean;
+    /** Number of links verified */
+    linksVerified: number;
+    /** Index of the first invalid link (-1 if all valid) */
+    firstInvalidIndex: number;
+    /** Verification time in milliseconds */
+    verificationTimeMs: number;
+    /** The terminal digest (last digest in the chain) */
+    terminalDigest: string;
+}
+/**
+ * DigestChain implements a rolling SHA-256 digest chain for tamper-evident audit trails.
+ *
+ * Each action logged through Kontext gets a cryptographic digest that chains
+ * to all prior actions, creating a tamper-evident audit trail without
+ * blockchain overhead.
+ *
+ * Properties:
+ * - Tamper-evident: altering any past event breaks the chain
+ * - Independently verifiable: any party can recompute and verify
+ * - Energy efficient: <0.00001 kWh per event (99.97% less than PoS)
+ * - Fast: <10ms verification at p95
+ *
+ * @example
+ * ```typescript
+ * const chain = new DigestChain();
+ *
+ * // Each action gets a digest link
+ * const link = chain.append(action);
+ * console.log(link.digest); // SHA-256 hash
+ *
+ * // Verify the entire chain
+ * const result = chain.verify();
+ * console.log(result.valid); // true if untampered
+ * ```
+ */
+declare class DigestChain {
+    private links;
+    private currentDigest;
+    private readonly hrtimeBase;
+    constructor();
+    /**
+     * Append an action to the digest chain.
+     *
+     * Computes: HD = SHA-256(HD-1 || Serialize(ED) || SD)
+     *
+     * @param action - The action log entry to chain
+     * @returns The digest link for this event
+     */
+    append(action: ActionLog): DigestLink;
+    /**
+     * Get the terminal digest — the latest digest in the chain.
+     * This can be embedded in outgoing messages as proof of the entire action history.
+     */
+    getTerminalDigest(): string;
+    /**
+     * Get the number of links in the chain.
+     */
+    getChainLength(): number;
+    /**
+     * Get all digest links in the chain.
+     */
+    getLinks(): ReadonlyArray<DigestLink>;
+    /**
+     * Get a specific digest link by sequence number.
+     */
+    getLink(sequence: number): DigestLink | undefined;
+    /**
+     * Verify the integrity of the entire digest chain.
+     *
+     * Recomputes every digest from the genesis hash and compares.
+     * Any tampering (modified, inserted, deleted, or reordered events)
+     * will cause verification to fail.
+     *
+     * @param actions - The original action logs to verify against
+     * @returns Verification result with timing data
+     */
+    verify(actions: ActionLog[]): DigestVerification;
+    /**
+     * Verify a single link in isolation (given the expected prior digest).
+     *
+     * @param link - The digest link to verify
+     * @param action - The action data for this link
+     * @param expectedPriorDigest - The expected prior digest
+     * @returns Whether the link is valid
+     */
+    verifyLink(link: DigestLink, action: ActionLog, expectedPriorDigest: string): boolean;
+    /**
+     * Export the chain data for independent verification by a third party.
+     * Includes all links and enough data for recomputation.
+     */
+    exportChain(): {
+        genesisHash: string;
+        links: DigestLink[];
+        terminalDigest: string;
+    };
+    /**
+     * Compute: HD = SHA-256(HD-1 || Serialize(ED) || SD)
+     */
+    private computeDigest;
+    /**
+     * Deterministically serialize an action log for digest computation.
+     * Uses sorted keys to ensure consistent serialization regardless of
+     * property insertion order. Excludes digest/priorDigest fields since
+     * those are computed from this serialization.
+     */
+    private serialize;
+    /**
+     * Derive a salt from the event's high-precision timestamp.
+     * SD = SHA-256(microsecond_timestamp)
+     */
+    private deriveSalt;
+    /**
+     * Get a microsecond-precision timestamp.
+     * Combines wall clock time with high-resolution timer for sub-millisecond precision.
+     */
+    private getPrecisionTimestamp;
+}
+/**
+ * Independently verify a digest chain exported from another Kontext instance.
+ * This enables third-party verification without access to the original SDK.
+ *
+ * @param chain - The exported chain data
+ * @param actions - The original action logs
+ * @returns Whether the chain is valid
+ */
+declare function verifyExportedChain(chain: {
+    genesisHash: string;
+    links: DigestLink[];
+    terminalDigest: string;
+}, actions: ActionLog[]): DigestVerification;
+
+/**
+ * Main Kontext SDK client. Provides a unified interface to all SDK features:
+ * action logging, task confirmation, audit export, trust scoring, and
+ * anomaly detection.
+ *
+ * Supports two operating modes:
+ * - **Local mode** (no API key): All data stored locally, suitable for
+ *   open-source usage and development.
+ * - **Cloud mode** (with API key): Data synced to Kontext API for
+ *   persistent storage and advanced features.
+ *
+ * @example
+ * ```typescript
+ * import { Kontext } from '@kontext/sdk';
+ *
+ * const kontext = Kontext.init({
+ *   projectId: 'my-project',
+ *   environment: 'development',
+ * });
+ *
+ * await kontext.logTransaction({
+ *   txHash: '0x...',
+ *   chain: 'base',
+ *   amount: '100',
+ *   token: 'USDC',
+ *   from: '0xSender',
+ *   to: '0xReceiver',
+ *   agentId: 'agent-1',
+ * });
+ * ```
+ */
+declare class Kontext {
+    private readonly config;
+    private readonly store;
+    private readonly logger;
+    private readonly taskManager;
+    private readonly auditExporter;
+    private readonly trustScorer;
+    private readonly anomalyDetector;
+    private readonly mode;
+    private constructor();
+    /**
+     * Initialize the Kontext SDK.
+     *
+     * @param config - Configuration options
+     * @returns Initialized Kontext client instance
+     *
+     * @example
+     * ```typescript
+     * // Local/OSS mode (no API key)
+     * const kontext = Kontext.init({
+     *   projectId: 'my-project',
+     *   environment: 'development',
+     * });
+     *
+     * // Cloud mode (with API key)
+     * const kontext = Kontext.init({
+     *   apiKey: 'sk_live_...',
+     *   projectId: 'my-project',
+     *   environment: 'production',
+     * });
+     * ```
+     */
+    static init(config: KontextConfig): Kontext;
+    /**
+     * Get the current operating mode.
+     */
+    getMode(): KontextMode;
+    /**
+     * Get the current configuration (API key is masked).
+     */
+    getConfig(): Omit<KontextConfig, 'apiKey'> & {
+        apiKey?: string;
+    };
+    /**
+     * Log a generic agent action.
+     *
+     * @param input - Action details
+     * @returns The created action log entry
+     */
+    log(input: LogActionInput): Promise<ActionLog>;
+    /**
+     * Log a cryptocurrency transaction with full chain details.
+     *
+     * @param input - Transaction details
+     * @returns The created transaction record
+     */
+    logTransaction(input: LogTransactionInput): Promise<TransactionRecord>;
+    /**
+     * Flush any pending log batches.
+     */
+    flushLogs(): Promise<void>;
+    /**
+     * Create a new tracked task that requires evidence for confirmation.
+     *
+     * @param input - Task details including required evidence types
+     * @returns The created task
+     */
+    createTask(input: CreateTaskInput): Promise<Task>;
+    /**
+     * Confirm a task by providing evidence.
+     *
+     * @param input - Task ID and evidence data
+     * @returns The confirmed task
+     */
+    confirmTask(input: ConfirmTaskInput): Promise<Task>;
+    /**
+     * Get the current status of a task.
+     *
+     * @param taskId - Task identifier
+     * @returns The task or undefined if not found
+     */
+    getTaskStatus(taskId: string): Promise<Task | undefined>;
+    /**
+     * Mark a task as in-progress.
+     *
+     * @param taskId - Task identifier
+     * @returns The updated task
+     */
+    startTask(taskId: string): Promise<Task>;
+    /**
+     * Mark a task as failed.
+     *
+     * @param taskId - Task identifier
+     * @param reason - Reason for failure
+     * @returns The updated task
+     */
+    failTask(taskId: string, reason: string): Promise<Task>;
+    /**
+     * Get all tasks, optionally filtered by status.
+     *
+     * @param status - Optional status filter
+     * @returns Array of tasks
+     */
+    getTasks(status?: TaskStatus): Task[];
+    /**
+     * Export audit data in JSON or CSV format.
+     *
+     * @param options - Export configuration
+     * @returns Export result with formatted data
+     */
+    export(options: ExportOptions): Promise<ExportResult>;
+    /**
+     * Generate a compliance report for a given period.
+     *
+     * @param options - Report configuration
+     * @returns Compliance report with summary and detailed records
+     */
+    generateReport(options: ReportOptions): Promise<ComplianceReport>;
+    /**
+     * Generate a Suspicious Activity Report (SAR) template.
+     *
+     * This produces a structured SAR template populated with data from the SDK.
+     * It is a template/structure, not an actual regulatory filing.
+     *
+     * @param options - Report configuration
+     * @returns SAR report template
+     */
+    generateSARReport(options: ReportOptions): Promise<SARReport>;
+    /**
+     * Generate a Currency Transaction Report (CTR) template.
+     *
+     * This produces a structured CTR template for transactions that meet or
+     * exceed reporting thresholds. It is a template/structure, not an actual
+     * regulatory filing.
+     *
+     * @param options - Report configuration
+     * @returns CTR report template
+     */
+    generateCTRReport(options: ReportOptions): Promise<CTRReport>;
+    /**
+     * Get the trust score for an agent.
+     *
+     * @param agentId - Agent identifier
+     * @returns Trust score with factor breakdown
+     */
+    getTrustScore(agentId: string): Promise<TrustScore>;
+    /**
+     * Evaluate the risk of a specific transaction.
+     *
+     * @param tx - Transaction to evaluate
+     * @returns Transaction evaluation with risk score and recommendation
+     */
+    evaluateTransaction(tx: LogTransactionInput): Promise<TransactionEvaluation>;
+    /**
+     * Enable anomaly detection with the specified rules and thresholds.
+     *
+     * @param config - Detection configuration
+     */
+    enableAnomalyDetection(config: AnomalyDetectionConfig): void;
+    /**
+     * Disable anomaly detection.
+     */
+    disableAnomalyDetection(): void;
+    /**
+     * Register a callback for anomaly events.
+     *
+     * @param callback - Function to call when an anomaly is detected
+     * @returns Unsubscribe function
+     */
+    onAnomaly(callback: AnomalyCallback): () => void;
+    /**
+     * Get the terminal digest — the latest SHA-256 hash in the rolling digest chain.
+     * Embed this in outgoing messages as tamper-evident proof of the entire action history.
+     *
+     * @returns The terminal SHA-256 digest hex string
+     */
+    getTerminalDigest(): string;
+    /**
+     * Verify the integrity of the digest chain.
+     * Recomputes every digest from genesis and compares against stored values.
+     * Any tampering will cause verification to fail.
+     *
+     * @returns Verification result with timing and validity data
+     */
+    verifyDigestChain(): DigestVerification;
+    /**
+     * Export the digest chain for independent third-party verification.
+     *
+     * @returns Chain data including genesis hash, all links, and terminal digest
+     */
+    exportDigestChain(): {
+        genesisHash: string;
+        links: DigestLink[];
+        terminalDigest: string;
+    };
+    /**
+     * Run USDC-specific compliance checks on a transaction.
+     *
+     * @param tx - Transaction to check
+     * @returns Compliance check result
+     */
+    checkUsdcCompliance(tx: LogTransactionInput): UsdcComplianceCheck;
+    /**
+     * Gracefully shut down the SDK, flushing any pending data.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * USDC-specific compliance helper functions.
+ *
+ * Provides pre-built compliance checks for USDC transactions on Base and
+ * Ethereum, aligned with the GENIUS Act requirements for stablecoin transfers.
+ *
+ * Checks include:
+ * - Token validation (is it USDC?)
+ * - Chain support validation
+ * - Amount threshold checks (EDD, reporting, large tx)
+ * - Address format validation
+ * - Sanctions screening (placeholder for OFAC integration)
+ * - Transfer limit checks
+ */
+declare class UsdcCompliance {
+    /**
+     * Run a full compliance check on a USDC transaction.
+     *
+     * @param tx - Transaction to evaluate
+     * @returns UsdcComplianceCheck with pass/fail results and recommendations
+     *
+     * @example
+     * ```typescript
+     * const check = UsdcCompliance.checkTransaction({
+     *   txHash: '0x...',
+     *   chain: 'base',
+     *   amount: '5000',
+     *   token: 'USDC',
+     *   from: '0xSender...',
+     *   to: '0xReceiver...',
+     *   agentId: 'agent-1',
+     * });
+     * if (!check.compliant) {
+     *   console.log('Non-compliant:', check.recommendations);
+     * }
+     * ```
+     */
+    static checkTransaction(tx: LogTransactionInput): UsdcComplianceCheck;
+    /**
+     * Get the USDC contract address for a given chain.
+     *
+     * @param chain - The blockchain network
+     * @returns The USDC contract address, or undefined for unsupported chains
+     */
+    static getContractAddress(chain: Chain): string | undefined;
+    /**
+     * Get the chains supported for USDC compliance monitoring.
+     */
+    static getSupportedChains(): Chain[];
+    private static checkTokenType;
+    private static checkChainSupport;
+    private static checkAddressFormat;
+    private static checkAmountValid;
+    private static checkSanctions;
+    private static checkEnhancedDueDiligence;
+    private static checkReportingThreshold;
+    private static generateRecommendations;
+}
+
+/** CCTP message status */
+type CCTPMessageStatus = 'pending' | 'attested' | 'confirmed' | 'failed';
+/** A cross-chain transfer record */
+interface CrossChainTransfer {
+    /** Unique transfer identifier */
+    id: string;
+    /** Source chain */
+    sourceChain: Chain;
+    /** Destination chain */
+    destinationChain: Chain;
+    /** CCTP domain ID for source */
+    sourceDomain: number;
+    /** CCTP domain ID for destination */
+    destinationDomain: number;
+    /** Transfer amount (string to preserve precision) */
+    amount: string;
+    /** Token being transferred */
+    token: Token;
+    /** Sender address on source chain */
+    sender: string;
+    /** Recipient address on destination chain */
+    recipient: string;
+    /** Source chain transaction hash */
+    sourceTxHash: string;
+    /** Destination chain transaction hash (set after confirmation) */
+    destinationTxHash: string | null;
+    /** CCTP message hash for attestation tracking */
+    messageHash: string | null;
+    /** Current status of the transfer */
+    status: CCTPMessageStatus;
+    /** Nonce from the CCTP MessageSent event */
+    nonce: number | null;
+    /** Timestamp when the transfer was initiated */
+    initiatedAt: string;
+    /** Timestamp when attestation was received */
+    attestedAt: string | null;
+    /** Timestamp when the transfer was confirmed on destination */
+    confirmedAt: string | null;
+    /** Correlation ID linking source and destination actions */
+    correlationId: string;
+    /** Agent that initiated the transfer */
+    agentId: string;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}
+/** Input for initiating a cross-chain transfer record */
+interface InitiateCCTPTransferInput {
+    /** Source chain */
+    sourceChain: Chain;
+    /** Destination chain */
+    destinationChain: Chain;
+    /** Transfer amount */
+    amount: string;
+    /** Token being transferred */
+    token: Token;
+    /** Sender address */
+    sender: string;
+    /** Recipient address */
+    recipient: string;
+    /** Source chain transaction hash (from depositForBurn) */
+    sourceTxHash: string;
+    /** Agent initiating the transfer */
+    agentId: string;
+    /** Optional nonce from the MessageSent event */
+    nonce?: number;
+    /** Optional correlation ID */
+    correlationId?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for recording a CCTP attestation */
+interface CCTPAttestationInput {
+    /** The cross-chain transfer ID */
+    transferId: string;
+    /** The message hash from the attestation service */
+    messageHash: string;
+    /** Optional attestation metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for confirming a cross-chain transfer on destination */
+interface ConfirmCCTPTransferInput {
+    /** The cross-chain transfer ID */
+    transferId: string;
+    /** Destination chain transaction hash (from receiveMessage) */
+    destinationTxHash: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Validation result for a cross-chain transfer */
+interface CCTPValidationResult {
+    /** Whether the transfer configuration is valid */
+    valid: boolean;
+    /** Validation checks performed */
+    checks: CCTPValidationCheck[];
+    /** Overall risk level */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Recommendations */
+    recommendations: string[];
+}
+/** Individual validation check */
+interface CCTPValidationCheck {
+    /** Check name */
+    name: string;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Description */
+    description: string;
+    /** Severity if failed */
+    severity: AnomalySeverity;
+}
+/** Cross-chain audit trail entry */
+interface CrossChainAuditEntry {
+    /** The transfer record */
+    transfer: CrossChainTransfer;
+    /** Source chain action log ID (from logTransaction) */
+    sourceActionId: string | null;
+    /** Destination chain action log ID (from logTransaction) */
+    destinationActionId: string | null;
+    /** Whether source and destination are linked */
+    linked: boolean;
+    /** Duration from initiation to confirmation in milliseconds */
+    durationMs: number | null;
+}
+/**
+ * CCTPTransferManager handles cross-chain transfer tracking and validation
+ * for Circle's Cross-Chain Transfer Protocol.
+ *
+ * Provides:
+ * - Transfer validation (source chain to destination chain)
+ * - CCTP message attestation logging
+ * - Cross-chain audit trail linking
+ * - Transfer lifecycle tracking (pending -> attested -> confirmed)
+ */
+declare class CCTPTransferManager {
+    private transfers;
+    private actionLinks;
+    /**
+     * Validate a cross-chain transfer before execution.
+     *
+     * Checks include:
+     * - Source and destination chain support
+     * - Route validity (different chains)
+     * - Token support on both chains
+     * - Amount validation
+     * - Address format validation
+     *
+     * @param input - Transfer details to validate
+     * @returns Validation result with checks and recommendations
+     */
+    validateTransfer(input: InitiateCCTPTransferInput): CCTPValidationResult;
+    /**
+     * Record a new cross-chain transfer initiated via CCTP depositForBurn.
+     *
+     * @param input - Transfer initiation details
+     * @returns The created CrossChainTransfer record
+     */
+    initiateTransfer(input: InitiateCCTPTransferInput): CrossChainTransfer;
+    /**
+     * Record a CCTP attestation for a pending transfer.
+     * Called after the attestation service has signed the burn message.
+     *
+     * @param input - Attestation details
+     * @returns The updated CrossChainTransfer record
+     * @throws Error if transfer not found or not in pending status
+     */
+    recordAttestation(input: CCTPAttestationInput): CrossChainTransfer;
+    /**
+     * Confirm a cross-chain transfer has been received on the destination chain.
+     * Called after receiveMessage has been executed on the destination.
+     *
+     * @param input - Confirmation details
+     * @returns The updated CrossChainTransfer record
+     * @throws Error if transfer not found or not in attested status
+     */
+    confirmTransfer(input: ConfirmCCTPTransferInput): CrossChainTransfer;
+    /**
+     * Mark a transfer as failed.
+     *
+     * @param transferId - The transfer to mark as failed
+     * @param reason - Reason for failure
+     * @returns The updated CrossChainTransfer record
+     */
+    failTransfer(transferId: string, reason: string): CrossChainTransfer;
+    /**
+     * Link a Kontext action log ID to a cross-chain transfer.
+     * Used to correlate source and destination chain actions in the audit trail.
+     *
+     * @param transferId - The cross-chain transfer ID
+     * @param actionId - The action log ID to link
+     * @param side - Whether this is the source or destination action
+     */
+    linkAction(transferId: string, actionId: string, side: 'source' | 'destination'): void;
+    /**
+     * Get a cross-chain transfer by ID.
+     */
+    getTransfer(transferId: string): CrossChainTransfer | undefined;
+    /**
+     * Get all cross-chain transfers, optionally filtered by status.
+     */
+    getTransfers(status?: CCTPMessageStatus): CrossChainTransfer[];
+    /**
+     * Get transfers by correlation ID.
+     * Useful for finding all transfers related to a single workflow.
+     */
+    getTransfersByCorrelation(correlationId: string): CrossChainTransfer[];
+    /**
+     * Build a cross-chain audit trail for a given transfer.
+     * Links source and destination chain actions together.
+     *
+     * @param transferId - The transfer to build an audit trail for
+     * @returns CrossChainAuditEntry with linked action references
+     */
+    getAuditEntry(transferId: string): CrossChainAuditEntry | undefined;
+    /**
+     * Build audit trail entries for all transfers, optionally filtered.
+     *
+     * @param agentId - Optional filter by agent
+     * @returns Array of CrossChainAuditEntry records
+     */
+    getAuditTrail(agentId?: string): CrossChainAuditEntry[];
+    /**
+     * Get the CCTP domain ID for a given chain.
+     *
+     * @param chain - The blockchain network
+     * @returns The CCTP domain ID, or undefined for unsupported chains
+     */
+    static getDomainId(chain: Chain): number | undefined;
+    /**
+     * Get the chains supported for CCTP transfers.
+     */
+    static getSupportedChains(): Chain[];
+    private checkChainSupport;
+    private checkRouteValidity;
+    private checkTokenSupport;
+    private checkAmountValidity;
+    private checkAddressFormat;
+    private generateRecommendations;
+}
+
+/** Supported webhook event types */
+type WebhookEventType = 'anomaly.detected' | 'task.confirmed' | 'task.failed' | 'trust.score_changed';
+/** Webhook registration configuration */
+interface WebhookConfig {
+    /** Unique identifier for this webhook */
+    id: string;
+    /** Target URL to receive webhook POST requests */
+    url: string;
+    /** Event types to listen for */
+    events: WebhookEventType[];
+    /** Optional secret for HMAC signature verification */
+    secret?: string;
+    /** Whether this webhook is active */
+    active: boolean;
+    /** When this webhook was registered */
+    createdAt: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for registering a new webhook */
+interface RegisterWebhookInput {
+    /** Target URL */
+    url: string;
+    /** Event types to listen for */
+    events: WebhookEventType[];
+    /** Optional secret for payload signing */
+    secret?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Webhook delivery payload */
+interface WebhookPayload {
+    /** Unique delivery ID */
+    id: string;
+    /** Event type */
+    event: WebhookEventType;
+    /** Timestamp of the event */
+    timestamp: string;
+    /** Event-specific data */
+    data: Record<string, unknown>;
+}
+/** Result of a webhook delivery attempt */
+interface WebhookDeliveryResult {
+    /** Webhook ID */
+    webhookId: string;
+    /** Delivery payload ID */
+    payloadId: string;
+    /** Whether delivery succeeded */
+    success: boolean;
+    /** HTTP status code (if applicable) */
+    statusCode: number | null;
+    /** Number of attempts made */
+    attempts: number;
+    /** Error message if failed */
+    error: string | null;
+    /** Timestamp of last attempt */
+    lastAttemptAt: string;
+}
+/** Retry configuration */
+interface WebhookRetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Base delay in milliseconds for exponential backoff */
+    baseDelayMs: number;
+    /** Maximum delay in milliseconds */
+    maxDelayMs: number;
+}
+/**
+ * WebhookManager handles registration and delivery of webhook notifications
+ * for SDK events including anomaly detection, task confirmation, and trust
+ * score changes.
+ *
+ * Features:
+ * - Register multiple webhook URLs with event type filtering
+ * - Automatic retry with exponential backoff on delivery failure
+ * - Delivery result tracking
+ * - Enable/disable individual webhooks
+ *
+ * @example
+ * ```typescript
+ * const manager = new WebhookManager();
+ *
+ * manager.register({
+ *   url: 'https://example.com/webhooks/kontext',
+ *   events: ['anomaly.detected', 'task.confirmed'],
+ * });
+ *
+ * // Webhooks fire automatically when events occur
+ * await manager.notifyAnomalyDetected(anomalyEvent);
+ * ```
+ */
+declare class WebhookManager {
+    private webhooks;
+    private deliveryResults;
+    private retryConfig;
+    private fetchFn;
+    constructor(retryConfig?: Partial<WebhookRetryConfig>, fetchFn?: typeof fetch);
+    /**
+     * Register a new webhook endpoint.
+     *
+     * @param input - Webhook configuration
+     * @returns The created WebhookConfig
+     */
+    register(input: RegisterWebhookInput): WebhookConfig;
+    /**
+     * Unregister a webhook by ID.
+     *
+     * @param webhookId - The webhook to remove
+     * @returns Whether the webhook was found and removed
+     */
+    unregister(webhookId: string): boolean;
+    /**
+     * Enable or disable a webhook.
+     *
+     * @param webhookId - The webhook to update
+     * @param active - Whether to enable or disable
+     * @returns The updated WebhookConfig, or undefined if not found
+     */
+    setActive(webhookId: string, active: boolean): WebhookConfig | undefined;
+    /**
+     * Get all registered webhooks.
+     */
+    getWebhooks(): WebhookConfig[];
+    /**
+     * Get a specific webhook by ID.
+     */
+    getWebhook(webhookId: string): WebhookConfig | undefined;
+    /**
+     * Get delivery results for a specific webhook or all webhooks.
+     */
+    getDeliveryResults(webhookId?: string): WebhookDeliveryResult[];
+    /**
+     * Notify all subscribed webhooks of an anomaly detection event.
+     *
+     * @param anomaly - The detected anomaly event
+     * @returns Array of delivery results
+     */
+    notifyAnomalyDetected(anomaly: AnomalyEvent): Promise<WebhookDeliveryResult[]>;
+    /**
+     * Notify all subscribed webhooks of a task confirmation.
+     *
+     * @param task - The confirmed task
+     * @returns Array of delivery results
+     */
+    notifyTaskConfirmed(task: Task): Promise<WebhookDeliveryResult[]>;
+    /**
+     * Notify all subscribed webhooks of a task failure.
+     *
+     * @param task - The failed task
+     * @returns Array of delivery results
+     */
+    notifyTaskFailed(task: Task): Promise<WebhookDeliveryResult[]>;
+    /**
+     * Notify all subscribed webhooks of a trust score change.
+     *
+     * @param trustScore - The new trust score
+     * @param previousScore - The previous score value (if known)
+     * @returns Array of delivery results
+     */
+    notifyTrustScoreChanged(trustScore: TrustScore, previousScore?: number): Promise<WebhookDeliveryResult[]>;
+    private deliver;
+    private deliverToWebhook;
+    private computeSignature;
+    private sleep;
+}
+
+export { type ActionLog, type AnomalyCallback, type AnomalyDetectionConfig, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type CCTPAttestationInput, type CCTPMessageStatus, CCTPTransferManager, type CCTPValidationCheck, type CCTPValidationResult, type CTRReport, type Chain, type ComplianceCheckResult, type ComplianceReport, type ConfirmCCTPTransferInput, type ConfirmTaskInput, type CreateTaskInput, type CrossChainAuditEntry, type CrossChainTransfer, type DateRange, DigestChain, type DigestLink, type DigestVerification, type Environment, type ExportFormat, type ExportOptions, type ExportResult, type InitiateCCTPTransferInput, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LogActionInput, type LogTransactionInput, type PrecisionTimestamp, type RegisterWebhookInput, type ReportOptions, type ReportSubject, type ReportType, type RiskFactor, type SARReport, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, UsdcCompliance, type UsdcComplianceCheck, type WebhookConfig, type WebhookDeliveryResult, type WebhookEventType, WebhookManager, type WebhookPayload, type WebhookRetryConfig, verifyExportedChain };