/**
 * @module transaction-tools
 * @description MCP tools for decoding, previewing, signing, and submitting Solana transactions.
 */
import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
import type { SapMcpContext } from '../../core/src/types.js';
import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
export type TransactionEncoding = 'base64' | 'base58';
type SolanaTransaction = Transaction | VersionedTransaction;
interface TransactionPolicyContext {
    config?: {
        programId?: string;
    };
}
interface DecodedTransaction {
    kind: 'legacy' | 'versioned';
    signatureCount: number;
    readonlySignedAccounts: number;
    readonlyUnsignedAccounts: number;
    requiredSignatures: number;
    instructionCount: number;
    accountKeys: string[];
    recentBlockhash: string;
    feePayer?: string;
    nativeTransferSol: number;
    tokenTransferCount: number;
    tokenTransfers: TokenTransferEstimate[];
    explicitApprovalRiskCount: number;
    explicitApprovalRisks: ExplicitApprovalRisk[];
    policyAllowed?: boolean;
    policyReason?: string;
}
interface NativeTransferEstimate {
    lamports: bigint;
    sol: number;
}
export interface TokenTransferEstimate {
    programId: string;
    instruction: 'transfer' | 'transferChecked' | 'transferCheckedWithFee';
    amount: string;
    source?: string;
    destination?: string;
    authority?: string;
    mint?: string;
    decimals?: number;
    feeAmount?: string;
}
export interface TransactionValueEstimate {
    nativeTransfer: NativeTransferEstimate;
    tokenTransfers: TokenTransferEstimate[];
    explicitApprovalRisks: ExplicitApprovalRisk[];
}
export interface ExplicitApprovalRisk {
    kind: 'addressLookupTable' | 'unknownProgram';
    instructionIndex?: number;
    programId?: string;
    reason: string;
}
export interface FinalizeTransactionInput {
    transaction?: string;
    transactionBase64?: string;
    encoding?: TransactionEncoding;
    submit?: boolean;
    skipPreflight?: boolean;
    maxRetries?: number;
    confirmationTimeoutMs?: number;
    commitment?: TransactionSubmitCommitment;
    submitViaRelay?: boolean;
    submitRelayUrl?: string;
    confirm?: boolean;
    signerProfile?: string;
    intentId?: string;
}
export type TransactionSubmitCommitment = 'processed' | 'confirmed' | 'finalized';
export interface TransactionSubmitLifecycleInput {
    signedTransaction: string;
    encoding?: TransactionEncoding;
    skipPreflight?: boolean;
    maxRetries?: number;
    confirmationTimeoutMs?: number;
    commitment?: TransactionSubmitCommitment;
    intentId?: string;
}
export interface TransactionSubmitLifecycleResult {
    success: boolean;
    submitted: true;
    signature: string;
    confirmationStatus: string;
    retrySafe: boolean;
    slot?: number;
    explorerUrl: string;
    audit: {
        intentId: string;
        submittedVia: 'local-rpc';
        confirmationTimeoutMs: number;
        desiredCommitment: TransactionSubmitCommitment;
        retrySafe: boolean;
        rule: string;
    };
    /** Pre-submit simulation result (when submit is attempted). */
    simulationResult?: {
        passed: boolean;
        computeUnitsConsumed?: number;
        logs?: string[];
        error?: string;
    };
}
/** Result when pre-submit simulation fails and the transaction is NOT submitted. */
export interface SimulationFailedResult {
    success: false;
    submitted: false;
    confirmationStatus: 'simulation_failed';
    retrySafe: true;
    simulationResult: {
        passed: boolean;
        computeUnitsConsumed?: number;
        logs?: string[];
        error?: string;
    };
}
interface RelaySubmitInput extends TransactionSubmitLifecycleInput {
    submitRelayUrl?: string;
}
type RelaySubmitResult = Omit<TransactionSubmitLifecycleResult, 'audit'> & {
    audit: Omit<TransactionSubmitLifecycleResult['audit'], 'submittedVia'> & {
        submittedVia: 'hosted-submit-relay';
        relayUrl: string;
        signerBoundary: 'local-signer-remote-submit-only';
    };
};
/**
 * @name decodeInputBytes
 * @description Decodes base64/base58 transaction text into raw bytes.
 * @param value - Encoded transaction string.
 * @param encoding - Encoding used by the incoming transaction.
 * @returns Raw serialized transaction bytes.
 */
export declare function decodeInputBytes(value: string, encoding?: TransactionEncoding): Buffer;
/**
 * @name deserializeTransaction
 * @description Deserializes a Solana transaction, preferring v0/versioned format before legacy fallback.
 * @param value - Encoded transaction string.
 * @param encoding - Encoding used by the incoming transaction.
 * @returns Deserialized Solana transaction.
 */
export declare function deserializeTransaction(value: string, encoding?: TransactionEncoding): SolanaTransaction;
/**
 * @name estimateNativeTransfer
 * @description Estimates native SOL leaving the signer, or all native SOL transfers when no signer filter is supplied.
 * @param transaction - Deserialized Solana transaction.
 * @param signer - Optional signer to filter outgoing transfers.
 * @returns Native transfer estimate in lamports and SOL.
 */
export declare function estimateNativeTransfer(transaction: SolanaTransaction, signer?: PublicKey): NativeTransferEstimate;
/**
 * @name estimateTokenTransfers
 * @description Estimates SPL Token and Token-2022 transfer instructions controlled by the signer.
 * @param transaction - Deserialized Solana transaction.
 * @param signer - Optional owner/authority signer filter.
 * @returns Token transfer estimates in base units.
 */
export declare function estimateTokenTransfers(transaction: SolanaTransaction, signer?: PublicKey): TokenTransferEstimate[];
export declare function estimateExplicitApprovalRisks(transaction: SolanaTransaction, signer?: PublicKey, context?: TransactionPolicyContext): ExplicitApprovalRisk[];
/**
 * @name estimateTransactionValue
 * @description Estimates native SOL and token value movement visible in a transaction.
 * @param transaction - Deserialized Solana transaction.
 * @param signer - Optional signer filter for outgoing value movement.
 * @returns Native SOL and token transfer estimates.
 */
export declare function estimateTransactionValue(transaction: SolanaTransaction, signer?: PublicKey, context?: TransactionPolicyContext): TransactionValueEstimate;
export declare function tokenTransferPolicyReason(estimate: TransactionValueEstimate): string;
export declare function explicitApprovalRiskPolicyReason(estimate: TransactionValueEstimate): string;
/**
 * @name assertTransactionPolicy
 * @description Enforces configured transaction value policy before signing or submitting a transaction.
 * @param context - Shared MCP runtime context.
 * @param transaction - Deserialized transaction to check.
 * @param signer - Optional signer filter for signing checks.
 */
export declare function assertTransactionPolicy(context: SapMcpContext, transaction: SolanaTransaction, signer?: PublicKey): Promise<TransactionValueEstimate>;
/**
 * @name serializeTransaction
 * @description Serializes a legacy or versioned transaction as base64.
 * @param transaction - Transaction to serialize.
 * @returns Base64 encoded transaction bytes.
 */
export declare function serializeTransaction(transaction: SolanaTransaction): string;
/**
 * @name submitSignedTransactionWithLifecycle
 * @description Submits a signed transaction through the configured local RPC and waits for a bounded confirmation result.
 * @param context - Shared MCP runtime context.
 * @param input - Signed transaction plus send/confirmation options.
 * @returns Submission lifecycle result with retry guidance.
 */
export declare function submitSignedTransactionWithLifecycle(context: SapMcpContext, input: TransactionSubmitLifecycleInput): Promise<TransactionSubmitLifecycleResult | SimulationFailedResult>;
/**
 * @name submitSignedTransactionViaRelay
 * @description Submits a signed transaction to the hosted OOBE submit relay. The relay never signs; it only broadcasts and confirms already-signed bytes.
 * @param input - Signed transaction plus send/confirmation options.
 * @returns Relay lifecycle result with retry guidance.
 */
export declare function submitSignedTransactionViaRelay(input: RelaySubmitInput): Promise<RelaySubmitResult>;
/**
 * @name describeTransaction
 * @description Builds a stable JSON preview from a Solana transaction.
 * @param transaction - Deserialized transaction.
 * @returns Transaction metadata safe to expose to MCP clients.
 */
export declare function describeTransaction(transaction: SolanaTransaction, context?: SapMcpContext): DecodedTransaction;
/**
 * @name finalizeTransactionWithLocalSigner
 * @description Preview, sign, and optionally submit a transaction with the local SAP MCP signer.
 * @param context - Shared MCP runtime context containing signer, policy, and RPC connection.
 * @param input - Transaction finalization request.
 * @returns Agent-readable finalization result without secret material.
 */
export declare function finalizeTransactionWithLocalSigner(context: SapMcpContext, input: FinalizeTransactionInput): Promise<Record<string, unknown>>;
/**
 * @name registerTransactionTools
 * @description Registers real transaction decode, preview, signing, and submission tools.
 * @param server - MCP server receiving the tool registrations.
 * @param context - Runtime context containing Solana connection and optional signer.
 */
export declare function registerTransactionTools(server: Server, context: SapMcpContext): void;
export {};
//# sourceMappingURL=transaction-tools.d.ts.map