RampManager: Orchestrate Fiat On-Ramp and Off-Ramp Flows

import {
  RampManager,
  ManualRampProvider,
  StellarAnchorProvider,
} from "@ankarachain/sdk";

new RampManager(provider: RampProvider, adapter?: IAdapter, opts?: RampManagerOptions)

import { RampManager, ManualRampProvider } from "@ankarachain/sdk";

const ramp = new RampManager(
  new ManualRampProvider({ exchangeRates: { NGN: 1 / 1580 }, feeBps: 150 }),
  factory.adapter,
  { settlementAddress: "0xYourRampSettlementAddress" }
);

static withProviders(
  providers: { onRamp: RampProvider; offRamp: RampProvider },
  adapter?: IAdapter,
  opts?: RampManagerOptions
): RampManager

import {
  RampManager,
  ManualRampProvider,
  StellarAnchorProvider,
} from "@ankarachain/sdk";

const ramp = RampManager.withProviders(
  {
    onRamp:  new ManualRampProvider(),          // local dev on-ramp
    offRamp: new StellarAnchorProvider({        // real anchor for off-ramp
      homeDomain: "cowrie.exchange",
      signer: freighterSigner,
    }),
  },
  adapter,
  { settlementAddress: contractAddress }
);

static connectAnchor(
  anchorHomeDomain: string,
  signer: StellarExternalSigner,
  adapter?: IAdapter,
  opts?: RampManagerOptions
): RampManager

const ramp = RampManager.connectAnchor(
  "cowrie.exchange",
  freighterSigner,
  adapter,
  { settlementAddress: contractAddress }
);

getQuote(input: RampQuoteInput): Promise<RampQuote>

const quote = await ramp.getQuote({
  direction:    "off-ramp",
  fiatCurrency: "NGN",
  tokenSymbol:  "USDC",
  countryCode:  "NG",
  tokenAmount:  "100",
});

console.log(`Rate: 1 USDC = ${quote.exchangeRate} NGN`);
console.log(`You get: ₦${quote.fiatAmount} (fee: ₦${quote.feeFiat})`);

initiateOnRamp(input: InitiateOnRampInput): Promise<RampSession>

const session = await ramp.initiateOnRamp({
  fiatAmount:       "150000",
  fiatCurrency:     "NGN",
  tokenSymbol:      "USDC",
  recipientAddress: "0xInvestorAddress",
  countryCode:      "NG",
});

// Redirect the user to complete payment
window.open(session.paymentUrl, "_blank");

initiateOffRamp(input: InitiateOffRampInput): Promise<RampSession>

const session = await ramp.initiateOffRamp({
  tokenAmount:  "100",
  tokenSymbol:  "USDC",
  fiatCurrency: "NGN",
  countryCode:  "NG",
  payoutAccount: {
    type:          "bank",
    accountNumber: "0123456789",
    accountName:   "Amina Saleh",
    bankCode:      "058", // GTBank
  },
});

getStatus(sessionId: string): Promise<RampSessionStatus>

import { RampSessionStatus } from "@ankarachain/sdk";

const status = await ramp.getStatus(session.sessionId);
if (status === RampSessionStatus.SETTLED) {
  console.log("Fiat delivered successfully.");
}

depositOffRamp(sessionId: string, tokenAddress: string, amount: bigint): Promise<string>

// EVM: approve first, then deposit
const usdc = new ethers.Contract(usdcAddress, ERC20_ABI, signer);
await usdc.approve(settlementAddress, ethers.parseUnits("100", 6));

const txHash = await ramp.depositOffRamp(session.sessionId, usdcAddress, ethers.parseUnits("100", 6));

confirmOffRampSettlement(sessionId: string): Promise<string>

refundOffRamp(sessionId: string): Promise<string>

recordOnRampSettlement(
  sessionId: string,
  recipient: string,
  tokenAddress: string,
  amount: bigint
): Promise<string>

getOffRampDeposit(sessionId: string): Promise<OffRampDeposit>

getOnRampRecord(sessionId: string): Promise<OnRampRecord>

ramp.providerName           // On-ramp provider name (backward compat)
ramp.onRampProviderName     // On-ramp provider name
ramp.offRampProviderName    // Off-ramp provider name
ramp.hasSettlementContract  // true if a settlementAddress was configured
ramp.settlementAddress      // The configured settlement address, or undefined

new ManualRampProvider(opts?: ManualRampProviderOptions)

import { ManualRampProvider } from "@ankarachain/sdk";

const provider = new ManualRampProvider({
  exchangeRates: { NGN: 1 / 1580, KES: 1 / 152, GHS: 1 / 16 },
  feeBps: 150, // 1.5%
});

// In tests, advance session state manually:
provider.markSettled(session.sessionId);
provider.markFailed(session.sessionId);

new StellarAnchorProvider(opts: StellarAnchorProviderOptions)

import {
  RampManager,
  ManualRampProvider,
  RampSessionStatus,
} from "@ankarachain/sdk";
import { ethers } from "ethers";

// 1. Set up RampManager with settlement contract
const ramp = new RampManager(
  new ManualRampProvider({ exchangeRates: { NGN: 1 / 1580 } }),
  factory.adapter,
  { settlementAddress: "0xRampSettlementAddress" }
);

// 2. Get a quote
const quote = await ramp.getQuote({
  direction: "off-ramp", fiatCurrency: "NGN",
  tokenSymbol: "USDC", countryCode: "NG", tokenAmount: "100",
});
console.log(`Estimated payout: ₦${quote.fiatAmount}`);

// 3. Initiate session
const session = await ramp.initiateOffRamp({
  tokenAmount:  "100",
  tokenSymbol:  "USDC",
  fiatCurrency: "NGN",
  countryCode:  "NG",
  payoutAccount: { type: "mobile-money", accountNumber: "08012345678", provider: "MTN" },
});

// 4. Approve and deposit tokens
const usdc = new ethers.Contract(usdcAddress, ERC20_ABI, signer);
await usdc.approve(ramp.settlementAddress, ethers.parseUnits("100", 6));
await ramp.depositOffRamp(session.sessionId, usdcAddress, ethers.parseUnits("100", 6));

// 5. Poll until settled (or use a webhook in production)
let status = await ramp.getStatus(session.sessionId);
while (status === RampSessionStatus.PENDING || status === RampSessionStatus.PROCESSING) {
  await new Promise(r => setTimeout(r, 5000));
  status = await ramp.getStatus(session.sessionId);
}

// 6. Confirm or refund
if (status === RampSessionStatus.SETTLED) {
  await ramp.confirmOffRampSettlement(session.sessionId);
} else {
  await ramp.refundOffRamp(session.sessionId);
}

enum RampSessionStatus {
  PENDING    = "pending",
  PROCESSING = "processing",
  SETTLED    = "settled",
  FAILED     = "failed",
  REFUNDED   = "refunded",
}

enum RampSettlementStatus {
  NONE     = 0,
  PENDING  = 1,
  SETTLED  = 2,
  REFUNDED = 3,
  RECORDED = 4,
}

interface RampQuote {
  direction:    RampDirection;
  fiatCurrency: string;
  fiatAmount:   string;
  tokenAmount:  string;
  tokenSymbol:  string;
  exchangeRate: string;
  feeFiat:      string;
  expiresAt:    number;  // unix seconds
}

interface RampSession {
  sessionId:    string;
  direction:    RampDirection;
  status:       RampSessionStatus;
  providerRef:  string;
  paymentUrl?:  string;  // on-ramp only
  createdAt:    number;
}

interface RampProvider {
  readonly name:    string;
  getQuote(input:   RampQuoteInput):      Promise<RampQuote>;
  initiateOnRamp(input: InitiateOnRampInput):  Promise<RampSession>;
  initiateOffRamp(input: InitiateOffRampInput): Promise<RampSession>;
  getStatus(sessionId: string):           Promise<RampSessionStatus>;
}