Provider Interface

/**
 * FinancialInstrumentProvider: the abstraction every Pair Instrument source implements.
 *
 * A provider knows how to describe an instrument, prove which onchain asset is canonical,
 * price it, say who may hold it, and plan/execute acquiring it. PairStreet product code
 * only ever talks to this interface (via the registry), never to a provider SDK directly.
 */
export interface FinancialInstrumentProvider {
  readonly id: string;
  readonly kind: ProviderKind;
  /** Mock providers exist only in development and their output must never be presented as real assets. */
  readonly isMock: boolean;

  getInstruments(): Promise<ProviderInstrument[]>;
  getInstrument(ref: string): Promise<ProviderInstrument | null>;
  /** The onchain representation holders actually receive. Null if the instrument has none (yet). */
  getCanonicalAsset(ref: string): Promise<CanonicalAsset | null>;
  getQuote(req: QuoteRequest): Promise<InstrumentQuote>;
  checkEligibility(req: EligibilityRequest): Promise<EligibilityResult>;
  getPurchaseRoute(req: QuoteRequest): Promise<PurchaseRoute>;
  /** Execute an acquisition plan. Live providers require a configured vault signer. */
  purchase(req: PurchaseRequest): Promise<PurchaseExecution>;
  getTransferRestrictions(ref: string): Promise<TransferRestrictions>;
  getInstrumentStatus(ref: string): Promise<InstrumentStatusReport>;
  getIssuerDocuments(ref: string): Promise<IssuerDocument[]>;
}

export type ProviderInstrument = {
  ref: string; // provider's own reference (stored as pair_instruments.provider_reference)
  slug: string;
  name: string;
  shortName: string;
  symbol: string;
  description: string;
  category: InstrumentCategory;
  subcategory?: string;
  country: string;
  region: Region;
  issuer: string;
  assetType: AssetType;
  icon: string;
  searchTerms: string;
  documentationUrl?: string;
};

export type CanonicalAsset = {
  network: "solana";
  mint: string;
  decimals: number;
  tokenProgram: "spl-token" | "token-2022" | "unknown";
  verification: InstrumentVerification;
  verifiedBy?: string;
};

export type QuoteRequest = {
  ref: string;
  inputMint: string; // settlement asset (USDC by default)
  inputAmountRaw: bigint;
  slippageBps?: number;
};

export type InstrumentQuote = {
  ref: string;
  inputMint: string;
  inputAmountRaw: string;
  outputAmountRaw: string;
  outputDecimals: number;
  /** USD per whole instrument unit implied by the quote. */
  priceUsd: number;
  priceImpactPct: number;
  source: string; // e.g. "jupiter", "dev-mock"
  quotedAt: string;
  isMock: boolean;
  raw?: unknown;
};

export type EligibilityRequest = { ref: string; country: string | null };
export type EligibilityResult =
  | { eligible: true }
  | { eligible: false; code: "REGION_RESTRICTED" | "UNKNOWN_REGION" | "KYC_REQUIRED" | "INSTRUMENT_UNAVAILABLE"; reason: string };

export type RouteStep = { kind: "swap" | "mint" | "rfq" | "transfer" | "simulated"; label: string; venue?: string };

export type PurchaseRoute = {
  mode: RouteMode;
  available: boolean;
  steps: RouteStep[];
  quote?: InstrumentQuote;
  /** Reasons the route cannot execute right now (missing signer, no liquidity, provider paused…). */
  blockers: string[];
};

export type PurchaseRequest = { route: PurchaseRoute; vaultAddress: string; inputAmountRaw: bigint };
export type PurchaseExecution = {
  outputAmountRaw: bigint;
  executionPriceUsd: number;
  txSignature: string | null;
  isMock: boolean;
};

export type TransferRestrictions = { transferable: boolean; summary: string; tokenProgram?: string };
export type InstrumentStatusReport = { status: InstrumentStatus; reason?: string; checkedAt: string };
export type IssuerDocument = { title: string; url: string; kind: "website" | "terms" | "prospectus" | "attestation" | "docs" };

// src/lib/domain.ts
export const PROVIDER_KINDS = [
  "tokenized_bonds",
  "tokenized_securities",
  "tokenized_fund",
  "real_estate",
  "commodity",
  "onchain_dex_route",
  "pair_registry",
  "dev_mock",
] as const;

export const ROUTE_MODES = ["ONCHAIN_SWAP", "PROVIDER_API", "RFQ", "ISSUER_MINT", "BROKER_ROUTE", "DEV_SIMULATED"] as const;

export const INSTRUMENT_STATUSES = ["active", "paused", "coming_soon", "provider_unavailable", "deprecated"] as const;

export const INSTRUMENT_VERIFICATION = [
  "dev_mock", // no real asset, development only
  "listed", // listed for pairing; onchain settlement asset not connected yet
  "issuer_listed", // mint published by issuer, routable, not independently verified by PairStreet
  "aggregator_verified", // verified by a token-list aggregator (e.g. Jupiter verified tag)
  "pairstreet_verified", // reviewed by PairStreet (manual process, future)
] as const;

// src/server/pair/router.ts (types and signatures)
export type AcquisitionPlan = {
  pairMarketId: string;
  instrumentRef: string;
  providerId: string;
  settlementMint: string;
  inputAmountRaw: string;
  mode: RouteMode;
  route: PurchaseRoute;
  executable: boolean;
  blockers: string[];
  ledgerMode: LedgerMode;
  plannedAt: string;
};

export type PlanInput = {
  pairMarketId: string;
  marketLedgerMode: LedgerMode;
  instrument: { providerReference: string; providerId: string; status: string; referencePriceUsd: number; decimals: number; shortName: string };
  settlementMint: string;
  inputAmountRaw: bigint;
};

export async function planAcquisition(input: PlanInput): Promise<AcquisitionPlan>;
export async function executeAcquisition(plan: AcquisitionPlan, vaultAddress: string): Promise<PurchaseExecution>;

/**
 * LaunchAdapter: the ONLY place PairStreet talks to launch/liquidity infrastructure.
 * Pump is the first venue. React components never import an adapter; they call
 * PairStreet API routes, which call services, which call the adapter.
 */
export interface LaunchAdapter {
  readonly venue: "pump";
  /** `dev_simulated` adapters never touch a chain; their results are flagged in every ledger row. */
  readonly ledgerMode: LedgerMode;

  /** Build the launch. Live: returns a partially-signed transaction (mint keypair signed) for the creator wallet. */
  prepareLaunch(input: PrepareLaunchInput): Promise<PreparedLaunch>;
  /** Verify the launch landed and return canonical venue addresses. */
  confirmLaunch(input: ConfirmLaunchInput): Promise<ConfirmedLaunch>;

  getMarket(mint: string): Promise<VenueMarket | null>;
  getGraduationStatus(mint: string): Promise<GraduationStatus>;
  quoteTrade(input: QuoteTradeInput): Promise<TradeQuote>;
  buildBuyTransaction(input: BuildTradeInput): Promise<PreparedTrade>;
  buildSellTransaction(input: BuildTradeInput): Promise<PreparedTrade>;
  /** Venue-native trade history. Production ingestion goes through the indexer, not this call. */
  getTrades(mint: string, opts: { limit: number; before?: string }): Promise<VenueTrade[]>;

  /** Creator-fee split (Pump fee-sharing config): build the setup tx for a launched mint. Live only. */
  buildFeeSetupTransaction?(input: { mint: string; creator: string; payer?: string; freshCurve?: boolean }): Promise<{ transactionBase64: string; lastValidBlockHeight: number }>;
  /** Read the on-chain creator-fee split for a mint. Null when no sharing config exists yet. */
  readFeeSplit?(mint: string): Promise<OnchainFeeSplit | null>;
  /** Permissionless: pay out accrued creator fees to the configured shareholders. */
  buildDistributeFeesTransaction?(input: { mint: string; payer: string }): Promise<{ transactionBase64: string; lastValidBlockHeight: number; distributableLamports: string; canDistribute: boolean }>;
}

// src/server/adapters/providers/types.ts
export class ProviderNotEnabledError extends Error {
  constructor(
    message: string,
    readonly missing: string[],
  ) {
    super(message);
    this.name = "ProviderNotEnabledError";
  }
}

{
  "error": {
    "code": "NOT_AVAILABLE",
    "message": "Live Pair acquisitions are not enabled in this build.",
    "missing": [
      "Pair Vault custody program or multisig signer",
      "Settlement executor service with Jupiter swap execution"
    ]
  }
}