@ar-agents/treasury 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,611 @@
+/**
+ * MantecaOffRampAdapter — the real PSAV off-ramp behind the treasury rail.
+ *
+ * Manteca (manteca.dev) is an Argentine crypto-fiat infrastructure provider. We
+ * integrate it as a registered-PSAV off-ramp; we never custody the conversion
+ * ourselves (CNV RG 1058/2025). This is a thin, typed client over Manteca's
+ * documented v2 API.
+ *
+ * GROUNDING — what is verified vs. what to confirm at onboarding
+ * ─────────────────────────────────────────────────────────────
+ * VERIFIED from docs.manteca.dev / developers.manteca.dev (jun-2026):
+ *   - Auth header is `md-api-key`.
+ *   - GET  /v2/prices/direct/{ticker}                 (a direct pair price)
+ *   - POST /v2/price-locks            {userAnyId,side,asset,against} -> {code,price}
+ *   - POST /v2/synthetics/ramp-off    {userId,sellAmount,sellAsset,withdrawAsset,
+ *                                       bankAccountId,externalId?} -> {id,status,stages[],...}
+ *   - GET  /v2/synthetics/{id}                         (synthetic status)
+ *   - POST /v2/onboarding-actions/add-bank-account     (register a CBU/CVU/alias; needs legalId)
+ *   - 429 responses carry internalStatus: "RATE_LIMITED".
+ *   - `externalId` is the idempotency key on synthetics/orders/withdraws.
+ *
+ * CONFIRM with your account before going to prod (all are config, one-line fixes):
+ *   - `baseUrl`: defaults to https://api.manteca.dev. The PUBLIC DOCS host is
+ *     developers.manteca.dev; the live API host ships with your credentials.
+ *   - `ticker`: defaults to "USDC_ARS"; confirm the exact pair string.
+ *   - The JSON shape of the price response and the synthetic status enum — both
+ *     are parsed DEFENSIVELY here and normalized; verify against a sandbox call.
+ *
+ * NOT yet integration-tested: Manteca onboarding is sales-gated (no self-serve
+ * keys), so this client is unit-tested against mocked HTTP (the request contract
+ * is pinned exactly). LIVE-PROBED 2026-06-24: api.manteca.dev is reachable but the
+ * live API host + price path ship per-account (GET /v2/prices/direct/USDC_ARS ->
+ * 404 unauth), so there is no public proving surface — confirm the host + ticker
+ * at onboarding. Going live = set the 3 config items above. See
+ * ../../TREASURY-FISCAL-RAIL.md §5. Run: `scripts/live-offramp.mjs manteca`.
+ */
+
+interface MantecaConfig {
+    /** API key, sent as the `md-api-key` header. */
+    apiKey: string;
+    /** Manteca user/company id that owns the crypto balance + the bank account. */
+    userId: string;
+    /** Registered destination bank account id (the society's CVU) for ARS payout. */
+    bankAccountId: string;
+    /**
+     * API base URL. Default https://api.manteca.dev. CONFIRM at onboarding — the
+     * public docs live at developers.manteca.dev; the live API host comes with
+     * your credentials.
+     */
+    baseUrl?: string;
+    /** Crypto asset sold. Default "USDC". */
+    sellAsset?: string;
+    /** Fiat received + withdrawn. Default "ARS". */
+    fiatAsset?: string;
+    /**
+     * Pair ticker for quote(). Default `${sellAsset}_${fiatAsset}` ("USDC_ARS").
+     * Confirm the exact string accepted by /v2/prices/direct for your account.
+     */
+    ticker?: string;
+    /** Injectable fetch (tests / non-global-fetch runtimes). Default global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable clock for the externalId fallback. Default Date.now. */
+    now?: () => number;
+}
+/** A non-2xx (or transport) failure from the Manteca API. */
+declare class MantecaApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/** 401/403 — bad or unauthorized api key. */
+declare class MantecaAuthError extends MantecaApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 429 — per-user rate limit (internalStatus RATE_LIMITED). */
+declare class MantecaRateLimitError extends MantecaApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class MantecaOffRampAdapter implements OffRampAdapter {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly sellAsset;
+    private readonly fiatAsset;
+    private readonly ticker;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(config: MantecaConfig);
+    private request;
+    /** Quote a USDC->ARS off-ramp using the direct sell-side price. */
+    quote(amountUsd: Usd): Promise<OffRampQuote>;
+    /**
+     * Fire the off-ramp synthetic: sell `amountUsd` of crypto and withdraw the ARS
+     * to the configured CVU. IRREVERSIBLE — gate behind requireConfirmation (RFC-001)
+     * and write to the signed audit log. Returns immediately with the synthetic id;
+     * the ARS settles asynchronously (poll getStatus). `arsReceived` is the EXPECTED
+     * amount at submission (from a fresh quote); the settled figure comes from getStatus.
+     */
+    convert(amountUsd: Usd, opts: {
+        externalId: string;
+    }): Promise<OffRampReceipt>;
+    /** Poll a ramp-off synthetic and normalize its settlement state. */
+    getStatus(txId: string): Promise<OffRampStatusReport>;
+    /**
+     * One-time onboarding helper: register the society's CBU/CVU/alias as a payout
+     * destination. The Manteca user must have `legalId` set first. Returns the
+     * created account id to use as `bankAccountId`.
+     */
+    registerBankAccount(input: {
+        cbuOrCvuOrAlias: string;
+        label?: string;
+    }): Promise<{
+        bankAccountId: string;
+        raw: unknown;
+    }>;
+}
+
+/**
+ * RipioOffRampAdapter — the second registered-PSAV off-ramp behind the treasury
+ * rail, proving the OffRampAdapter interface is provider-agnostic (no single-PSAV
+ * lock-in). Ripio's operating entity (Moonbird SRL) is a CNV-registered PSAV.
+ *
+ * Ripio's off-ramp is a SESSION model (unlike Manteca's sell-from-balance): you
+ * create a session bound to a fiat account (the society's CVU), Ripio returns a
+ * deposit ADDRESS, the society sends USDC there, and Ripio converts + pays ARS to
+ * the CVU. So convert() creates the session and returns the deposit address (on
+ * the receipt); completion needs an on-chain transfer the society makes from its
+ * wallet, then getStatus() tracks it.
+ *
+ * GROUNDING (docs.ripio.com, jun-2026):
+ *   - Auth: OAuth2 client-credentials. POST /oauth2/token/ with
+ *     `Authorization: Basic base64(clientId:clientSecret)` + body
+ *     `grant_type=client_credentials` -> { access_token, token_type, expires_in }.
+ *     Then `Authorization: Bearer <token>`.
+ *   - POST /api/v1/quotes/        { fromCurrency, toCurrency, fromAmount, chain, paymentMethodType }
+ *                                 -> { quoteId, rate, toAmount, finalToAmount, fees[], expiration }
+ *   - POST /api/v1/fiatAccounts/  { customerId, paymentMethodType, accountFields:{ alias_or_cvu_destination } }
+ *                                 -> { id, status }            (one-time CVU registration)
+ *   - POST /api/v1/offrampSession/ { fiatAccountId, ... }      -> { sessionId, depositAddresses:[{chain,address}], ... }
+ *   - GET  /api/v1/offrampSession/{id}                          -> session status
+ *
+ * CONFIRM at onboarding (all config, sales-gated credentials):
+ *   - baseUrl: defaults to the sandbox; pass prod to go live.
+ *   - `chain`: defaults to "BASE" — Ripio's public docs only enumerate ETHEREUM
+ *     in static examples; confirm Base/USDC is enabled via GET /api/v1/depositNetworks/.
+ *   - The exact offrampSession request body + status enum (parsed defensively here).
+ *
+ * Request contract pinned + unit-tested vs mocked HTTP. LIVE-PROBED 2026-06-24:
+ * the sandbox host is up and `POST /oauth2/token/` returns `{error:"invalid_client"}`
+ * (401) while `POST /api/v1/quotes/` returns 401 — the exact wire + error shapes
+ * this adapter handles (RipioAuthError), verified up to the credential boundary.
+ * Only sales-gated client creds remain; Ripio is the soonest path to a full live
+ * run (open sandbox + deposit simulation). Run: `scripts/live-offramp.mjs ripio`.
+ */
+
+declare const RIPIO_SANDBOX = "https://sandbox-b2b.ripio.com";
+declare const RIPIO_PROD = "https://b2b-api.ripio.com";
+interface RipioConfig {
+    clientId: string;
+    clientSecret: string;
+    /** Ripio B2B customer id (the KYC'd society). */
+    customerId: string;
+    /** Pre-registered fiat account id (the society's CVU). See registerFiatAccount. */
+    fiatAccountId: string;
+    /** API base URL. Default = sandbox. Pass RIPIO_PROD for live. */
+    baseUrl?: string;
+    /** Settlement chain. Default "BASE". CONFIRM Base is enabled for your account. */
+    chain?: string;
+    /** Crypto sold. Default "USDC". */
+    fromCurrency?: string;
+    /** Fiat received. Default "ARS". */
+    toCurrency?: string;
+    /** Default "bank_transfer". */
+    paymentMethodType?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+declare class RipioApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+declare class RipioAuthError extends RipioApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class RipioRateLimitError extends RipioApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** Normalize Ripio's off-ramp session status into our cross-PSAV enum. */
+declare function normalizeRipioStatus(raw: string | undefined): OffRampStatus;
+declare class RipioOffRampAdapter implements OffRampAdapter {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly chain;
+    private readonly fromCurrency;
+    private readonly toCurrency;
+    private readonly paymentMethodType;
+    private readonly fetchImpl;
+    private readonly now;
+    private token;
+    constructor(config: RipioConfig);
+    private getToken;
+    private request;
+    quote(amountUsd: Usd): Promise<OffRampQuote>;
+    /**
+     * Create an off-ramp session for `amountUsd`. Returns a receipt whose
+     * `depositAddress` is where the society must send the USDC to complete the
+     * payout; `txId` is the session id for getStatus. `arsReceived` is the EXPECTED
+     * amount (from a fresh quote); the settled figure comes from getStatus.
+     */
+    convert(amountUsd: Usd, opts: {
+        externalId: string;
+    }): Promise<OffRampReceipt>;
+    private pickDepositAddress;
+    getStatus(txId: string): Promise<OffRampStatusReport>;
+    /**
+     * One-time onboarding helper: register the society's CBU/CVU/alias as a fiat
+     * account payout destination. Returns the id to use as `fiatAccountId`.
+     */
+    registerFiatAccount(input: {
+        cbuOrCvuOrAlias: string;
+    }): Promise<{
+        fiatAccountId: string;
+        raw: unknown;
+    }>;
+}
+
+/**
+ * MuralOffRampAdapter — the self-onboard off-ramp behind the treasury rail.
+ *
+ * Mural (muralpay.com) is a stablecoin->fiat payouts API with deep LatAm rails.
+ * Unlike a sell-from-balance exchange (Manteca) or a deposit-session PSAV (Ripio),
+ * Mural is a PAYOUT model: you fund a Mural Account with USDC (on Base), then
+ * create + execute a Payout Request that converts USDC->ARS and pays a bank
+ * account (CBU/CVU/alias). We integrate it as the off-ramp; we never custody the
+ * conversion ourselves. Chosen as the proving path because onboarding is
+ * self-driven KYB (no sales gate) and it covers the full USDC->ARS-to-bank loop.
+ *
+ * GROUNDING — verified against Mural's OpenAPI spec + docs (jun-2026):
+ *   - Base URLs: prod https://api.muralpay.com ; sandbox https://api-staging.muralpay.com
+ *   - Auth: `authorization: Bearer <apiKey>` on all calls; `transfer-api-key:
+ *     <transferApiKey>` additionally on /execute (and /cancel). `on-behalf-of:
+ *     <organizationId>` scopes org operations.
+ *   - POST /api/payouts/fees/token-to-fiat  { tokenFeeRequests:[{amount:{tokenAmount,
+ *       tokenSymbol},fiatAndRailCode:"ars"}] } -> [{type:"success",exchangeRate,
+ *       exchangeFeePercentage,estimatedFiatAmount:{fiatAmount,fiatCurrencyCode},
+ *       feeTotal:{tokenAmount,tokenSymbol},...} | {type:"error",message,...}]
+ *   - POST /api/payouts/payout  { sourceAccountId, memo, payouts:[{amount:{tokenAmount,
+ *       tokenSymbol:"USDC"}, payoutDetails:{type:"fiat",bankName,bankAccountOwner,
+ *       fiatAndRailDetails:{type:"ars",symbol:"ARS",bankAccountNumber,documentNumber,
+ *       bankAccountNumberType:"CVU"|"CBU"|"ALIAS"}}, recipientInfo:{type:"business"|
+ *       "individual",...,physicalAddress}}] } -> { id, status:"AWAITING_EXECUTION" }
+ *   - POST /api/payouts/payout/{id}/execute    (transfer-api-key) -> status PENDING
+ *   - GET  /api/payouts/payout/{id}  -> { status:AWAITING_EXECUTION|PENDING|EXECUTED|
+ *       FAILED|CANCELED, payouts:[{details:{fiatPayoutStatus:{type},fiatAmount:{fiatAmount}}}] }
+ *   - USDC fund chain enum includes BASE; ARS rail code = "ars".
+ *
+ * CONFIRM at onboarding (config, one-line fixes):
+ *   - baseUrl: defaults to prod; set the sandbox while testing.
+ *   - The exact `recipientInfo.physicalAddress` shape your account requires
+ *     (passed through verbatim) and whether `on-behalf-of` is needed on payouts.
+ *   - Whether the fees `amount` field wants the {tokenAmount,tokenSymbol} object
+ *     (sent here) or a bare number — parsed/sent defensively; verify in sandbox.
+ *
+ * NOT yet live-integration-tested: Mural API keys need a Mural Organization +
+ * self-driven KYB (no self-serve key minting, but no sales gate either). Going
+ * live = KYB -> keys -> set the config -> run scripts/live-offramp.mjs mural.
+ * convert() moves real money; gate behind requireConfirmation (RFC-001).
+ */
+
+declare const MURAL_PROD = "https://api.muralpay.com";
+declare const MURAL_SANDBOX = "https://api-staging.muralpay.com";
+interface MuralConfig {
+    /** General API key — sent as `authorization: Bearer`. */
+    apiKey: string;
+    /** Transfer API key — sent as `transfer-api-key`, required to execute payouts. */
+    transferApiKey: string;
+    /** Mural Account id holding the USDC balance (the payout source). */
+    sourceAccountId: string;
+    /** Organization id; sent as `on-behalf-of` when present. */
+    organizationId?: string;
+    /** Destination bank (the society's ARS account). */
+    bankName: string;
+    bankAccountOwner: string;
+    /** CBU / CVU / alias value -> `bankAccountNumber`. */
+    cvu: string;
+    /** How `cvu` is identified. Default "CVU". */
+    cvuType?: "CVU" | "CBU" | "ALIAS";
+    /** Recipient tax/ID number (e.g. the society's CUIT) -> `documentNumber`. */
+    documentNumber: string;
+    /** Recipient identity for the payout (the society). */
+    recipient: {
+        type?: "business" | "individual";
+        /** Business name (type=business). */
+        name?: string;
+        /** Person name (type=individual). */
+        firstName?: string;
+        lastName?: string;
+        email?: string;
+        /** Passed through verbatim as recipientInfo.physicalAddress. */
+        physicalAddress: unknown;
+    };
+    /** API base URL. Default = prod. Pass MURAL_SANDBOX while testing. */
+    baseUrl?: string;
+    /** Crypto sold. Default "USDC". */
+    tokenSymbol?: string;
+    /** Fiat rail code. Default "ars". */
+    fiatRailCode?: string;
+    /** Injectable fetch (tests / non-global-fetch runtimes). */
+    fetchImpl?: typeof fetch;
+    /** Injectable clock for the externalId fallback. Default Date.now. */
+    now?: () => number;
+}
+/** A non-2xx (or transport) failure from the Mural API. */
+declare class MuralApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/** 401/403 — bad or unauthorized api key (or ToS not accepted). */
+declare class MuralAuthError extends MuralApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 429 — rate limited. */
+declare class MuralRateLimitError extends MuralApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Normalize Mural's status into our cross-PSAV enum. Prefers the per-payout
+ * `fiatPayoutStatus.type` (created/pending/on-hold/completed/failed/canceled/
+ * refund*) when present; else falls back to the request-level status. Note: a
+ * request status of EXECUTED only means the on-chain leg ran — the fiat may still
+ * be settling, so EXECUTED maps to PROCESSING unless the fiat leg is completed.
+ */
+declare function normalizeMuralStatus(requestStatus: string | undefined, fiatPayoutType?: string): OffRampStatus;
+declare class MuralOffRampAdapter implements OffRampAdapter {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly tokenSymbol;
+    private readonly fiatRailCode;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(config: MuralConfig);
+    private request;
+    /** Quote a USDC->ARS off-ramp via the token-to-fiat fees endpoint. */
+    quote(amountUsd: Usd): Promise<OffRampQuote>;
+    /**
+     * Create + execute the off-ramp payout: convert `amountUsd` USDC and pay ARS to
+     * the configured CBU/CVU. IRREVERSIBLE — gate behind requireConfirmation (RFC-001)
+     * and write to the signed audit log. Returns the payout-request id as txId;
+     * `arsReceived` is the EXPECTED amount (from a fresh quote), the settled figure
+     * comes from getStatus.
+     */
+    convert(amountUsd: Usd, opts: {
+        externalId: string;
+    }): Promise<OffRampReceipt>;
+    /** Poll a payout request and normalize its settlement state. */
+    getStatus(txId: string): Promise<OffRampStatusReport>;
+}
+
+/**
+ * The AFIP/ARCA fiscal layer of the treasury rail.
+ *
+ * (ARCA = Agencia de Recaudación y Control Aduanero, the continuator of AFIP per
+ * Decreto 953/2024, eff. 5-nov-2024. afip.gob.ar URLs still resolve.)
+ *
+ * THE HONEST FINDING (verified jun-2026): there is NO fully-autonomous, official
+ * channel for a private entity to pay its taxes at pay-time. So this module does
+ * NOT pretend to "pay AFIP." It does the parts that are real:
+ *   1. Compute the obligation (monotributo cuota here; cedular lives in index.ts).
+ *   2. Describe the settlement honestly — what is automatable vs. human-required.
+ * The treasury brain (index.ts) sizes + funds the ARS buffer so that whatever
+ * settlement rail the society configured can succeed on time.
+ *
+ * Why no autonomy (all verified against ARCA + MercadoPago official docs):
+ *   - WSCREATEVEP (create a VEP via web service) is enabled ONLY for public
+ *     organisms, not private taxpayers. Do not build on it.
+ *   - Monotributo débito automático CANNOT be enrolled via API — it is a one-time
+ *     portal/bank step. Once enrolled it runs PASSIVELY (the monthly cuota debits
+ *     itself). The agent cannot trigger it; it can only ensure the CVU is funded.
+ *   - There is NO MercadoPago API to pay a VEP — it is a manual in-app flow
+ *     (scan QR, or enter CUIT + VEP number).
+ * Full sourcing: ../../TREASURY-FISCAL-RAIL.md §3.
+ */
+
+/**
+ * Guard constant: documents (so nobody re-adds it) why WSCREATEVEP is unusable.
+ */
+declare const WSCREATEVEP_IS_GOV_ONLY: string;
+declare const MONOTRIBUTO_TABLE_EFFECTIVE = "2026-02-01";
+type MonotributoCategory = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K";
+type MonotributoActivity = "servicios" | "bienes";
+interface MonotributoRow {
+    category: MonotributoCategory;
+    /** Annual gross-income ceiling for the category, ARS. */
+    annualCapArs: Ars;
+    /** Monthly total cuota for a services taxpayer, ARS. */
+    cuotaServicios: Ars;
+    /** Monthly total cuota for a goods taxpayer, ARS. */
+    cuotaBienes: Ars;
+    /** I/J/K are only available when selling goods. */
+    bienesOnly: boolean;
+}
+declare const MONOTRIBUTO_2026: readonly MonotributoRow[];
+/** Monthly monotributo cuota for a category + activity, ARS. */
+declare function monotributoCuota(category: MonotributoCategory, activity: MonotributoActivity): Ars;
+/**
+ * The category an annual gross income falls into, for the given activity. A
+ * services taxpayer caps at H; returns null if income exceeds the regime ceiling
+ * (the taxpayer must move to the general regime).
+ */
+declare function categoryForAnnualIncome(annualArs: Ars, activity: MonotributoActivity): MonotributoCategory | null;
+type SettlementMethod = "debito_automatico" | "vep_manual" | "mp_manual";
+/**
+ * - `passive`: a one-time human enrolment makes future payments run themselves;
+ *   the agent only has to keep the CVU funded (débito automático).
+ * - `human-required`: a human must act for THIS payment (generate + pay a VEP).
+ */
+type SettlementAutonomy = "passive" | "human-required";
+interface SettlementPlan {
+    method: SettlementMethod;
+    autonomy: SettlementAutonomy;
+    /**
+     * Whether the agent can settle with zero human action at pay-time. Typed as the
+     * literal `false`: in jun-2026 NO official channel allows fully-autonomous tax
+     * payment by a private entity. The rail funds + instructs; it does not pay.
+     */
+    canAutoExecute: false;
+    amountArs: Ars;
+    /** Epoch ms the obligation is due. */
+    dueAtMs: number;
+    /** What must happen for this obligation to actually be paid. */
+    instruction: string;
+    /** One-time human setup this method needs (empty string if none). */
+    oneTimeSetup: string;
+}
+/**
+ * Describe how a given obligation gets settled under the chosen method. Pure +
+ * honest: the agent's autonomous part is funding the CVU (see index.ts
+ * fundTaxBuffer); the settlement itself is passive (débito) or human (VEP/MP).
+ */
+declare function settlementPlan(obligation: Obligation, method: SettlementMethod): SettlementPlan;
+
+/**
+ * @ar-agents/treasury — the fiscal/treasury rail for a Sociedad Automatizada.
+ *
+ * The moat half of the crypto<->fiat bridge: an autonomous society earns in
+ * crypto (USDC on Base) but must pay AFIP in pesos. This module is the pure,
+ * deterministic BRAIN of that loop: track balances, size the peso tax buffer,
+ * plan a just-in-time USDC->ARS conversion, and account for the Ganancias
+ * cedular tax on each disposal. The actual off-ramp (USDC->ARS payout to a CVU)
+ * is done by an OffRampAdapter wrapping a registered PSAV (Manteca / Ripio B2B);
+ * we integrate one, we do not become one (CNV RG 1058/2025).
+ *
+ * Pure functions (clock + fx injected, never read) so they are unit-testable and
+ * deterministic. Irreversible moves (convert, pay) must be gated by the agent's
+ * requireConfirmation (RFC-001) and written to the signed audit log by the caller.
+ */
+/** Stablecoin balance, USDC (the society earns here). */
+type Usd = number;
+/** Peso balance, ARS (held in a CVU; what AFIP is paid from). */
+type Ars = number;
+interface TreasuryState {
+    /** USDC balance (on Base). */
+    usd: Usd;
+    /** ARS balance (in the society's CVU). */
+    ars: Ars;
+    /**
+     * Average USD cost basis per USDC unit currently held. For USDC ~= 1, but the
+     * society may have acquired crypto that appreciated; cedular is on the gain.
+     */
+    costBasisPerUsd: number;
+}
+declare const ZERO_STATE: TreasuryState;
+type Denomination = "ARS" | "FOREIGN";
+declare const CEDULAR_RATE: Record<Denomination, number>;
+/**
+ * Cedular tax owed (in ARS) on disposing `amountUsd` of crypto with the given
+ * per-unit cost basis, at `fxRate` (ARS per USD). Taxed on the gain only; 0 if no gain.
+ */
+declare function cedularTax(amountUsd: Usd, costBasisPerUsd: number, fxRate: number, denom?: Denomination): Ars;
+type ObligationKind = "monotributo" | "vep" | "iibb" | "cedular";
+interface Obligation {
+    id: string;
+    kind: ObligationKind;
+    amountArs: Ars;
+    /** Epoch ms when it is due. */
+    dueAtMs: number;
+}
+/** The next obligation due at/after `nowMs`, or null. */
+declare function nextObligation(obligations: Obligation[], nowMs: number): Obligation | null;
+/**
+ * ARS needed to cover every obligation due within `horizonMs` from now, times a
+ * safety multiple (default 1.1) so a small fx move does not leave AFIP short.
+ */
+declare function requiredArsBuffer(obligations: Obligation[], nowMs: number, horizonMs: number, safety?: number): Ars;
+interface ConversionPlan {
+    /** How much USDC to convert now (0 = do nothing). */
+    convertUsd: Usd;
+    /** ARS expected from that conversion, net of spread. */
+    expectedArs: Ars;
+    reason: string;
+}
+/**
+ * Plan a just-in-time conversion: if the ARS balance is below `requiredArs`,
+ * convert only enough USDC (at `fxRate` net of `spread`) to top the buffer back
+ * up, capped by available USDC. Never over-converts (minimizes taxable disposals
+ * + fx exposure). Pure.
+ */
+declare function planConversion(state: TreasuryState, requiredArs: Ars, fxRate: number, spread?: number): ConversionPlan;
+interface OffRampReceipt {
+    amountUsd: Usd;
+    arsReceived: Ars;
+    /** ARS per USD actually realized (net of spread). */
+    rate: number;
+    txId: string;
+    /**
+     * Set by session-model PSAVs (Ripio): the on-chain address the society must
+     * send `amountUsd` USDC to in order to complete the off-ramp. Manteca (which
+     * sells from the platform balance) leaves it undefined.
+     */
+    depositAddress?: string;
+}
+/** Apply a completed off-ramp conversion to the state (USDC down, ARS up). */
+declare function applyConversion(state: TreasuryState, receipt: OffRampReceipt): TreasuryState;
+/** Apply a tax/obligation payment (ARS down). Throws if it would overdraw the CVU. */
+declare function applyPayment(state: TreasuryState, amountArs: Ars): TreasuryState;
+interface OffRampQuote {
+    amountUsd: Usd;
+    arsOut: Ars;
+    /** Gross ARS per USD before spread. */
+    rate: number;
+    spread: number;
+}
+/** Settlement state of an off-ramp, normalized across PSAVs. */
+type OffRampStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "UNKNOWN";
+interface OffRampStatusReport {
+    txId: string;
+    status: OffRampStatus;
+    /** ARS actually settled to the CVU once COMPLETED, if the PSAV reports it. */
+    arsSettled?: Ars;
+    /** Provider-native status string, kept for the signed audit log / forensics. */
+    raw?: string;
+}
+interface OffRampAdapter {
+    /** Quote a USDC->ARS conversion (net of spread). No side effects. */
+    quote(amountUsd: Usd): Promise<OffRampQuote>;
+    /**
+     * Execute the conversion + payout of ARS to the society's CVU. IRREVERSIBLE:
+     * the caller MUST gate this behind requireConfirmation (RFC-001) and log it.
+     * `opts.externalId` is a REQUIRED idempotency key — a STABLE id derived from the
+     * payment (e.g. obligation id + period + amount). Reuse the SAME key on retry so
+     * the PSAV deduplicates it and a retried convert never double-spends.
+     */
+    convert(amountUsd: Usd, opts: {
+        externalId: string;
+    }): Promise<OffRampReceipt>;
+    /**
+     * Poll the settlement of a prior convert(). A real off-ramp is ASYNCHRONOUS:
+     * the PSAV sells the crypto, then settles ARS to the CVU over seconds-to-minutes
+     * (Manteca models this as a multi-stage "synthetic"). Optional because the
+     * in-memory adapter settles instantly.
+     */
+    getStatus?(txId: string): Promise<OffRampStatusReport>;
+}
+/**
+ * Deterministic in-memory off-ramp for tests/dev (no network, no PSAV). A real
+ * adapter wraps Manteca's API Cripto / API Rampa (or Ripio B2B): fund a wallet
+ * with USDC -> POST a conversion -> ARS settles to the CVU -> webhook confirms.
+ */
+declare class InMemoryOffRampAdapter implements OffRampAdapter {
+    private readonly rate;
+    private readonly spread;
+    private readonly settled;
+    constructor(rate: number, spread?: number);
+    quote(amountUsd: Usd): Promise<OffRampQuote>;
+    convert(amountUsd: Usd, opts: {
+        externalId: string;
+    }): Promise<OffRampReceipt>;
+    /** The in-memory adapter settles instantly: any tx it issued is COMPLETED. */
+    getStatus(txId: string): Promise<OffRampStatusReport>;
+}
+/**
+ * One-shot helper: given the current state, the obligations, and an off-ramp,
+ * compute + (optionally) execute the conversion needed to fund the buffer. Returns
+ * the plan; if `offramp` is provided it also performs the conversion and returns
+ * the receipt + the resulting state. The convert() call is irreversible: only pass
+ * `offramp` from a path already behind requireConfirmation.
+ */
+declare function fundTaxBuffer(args: {
+    state: TreasuryState;
+    obligations: Obligation[];
+    nowMs: number;
+    horizonMs: number;
+    fxRate: number;
+    spread?: number;
+    safety?: number;
+    offramp?: OffRampAdapter;
+    /**
+     * Idempotency key for the off-ramp convert. Defaults to a deterministic id from
+     * the obligations being funded + the amount, so a retried fundTaxBuffer with the
+     * same inputs is deduplicated by the PSAV and never double-spends. Pass an
+     * explicit stable id to override.
+     */
+    externalId?: string;
+}): Promise<{
+    plan: ConversionPlan;
+    receipt?: OffRampReceipt;
+    state: TreasuryState;
+}>;
+
+export { type Ars, CEDULAR_RATE, type ConversionPlan, type Denomination, InMemoryOffRampAdapter, MONOTRIBUTO_2026, MONOTRIBUTO_TABLE_EFFECTIVE, MURAL_PROD, MURAL_SANDBOX, MantecaApiError, MantecaAuthError, type MantecaConfig, MantecaOffRampAdapter, MantecaRateLimitError, type MonotributoActivity, type MonotributoCategory, type MonotributoRow, MuralApiError, MuralAuthError, type MuralConfig, MuralOffRampAdapter, MuralRateLimitError, type Obligation, type ObligationKind, type OffRampAdapter, type OffRampQuote, type OffRampReceipt, type OffRampStatus, type OffRampStatusReport, RIPIO_PROD, RIPIO_SANDBOX, RipioApiError, RipioAuthError, type RipioConfig, RipioOffRampAdapter, RipioRateLimitError, type SettlementAutonomy, type SettlementMethod, type SettlementPlan, type TreasuryState, type Usd, WSCREATEVEP_IS_GOV_ONLY, ZERO_STATE, applyConversion, applyPayment, categoryForAnnualIncome, cedularTax, fundTaxBuffer, monotributoCuota, nextObligation, normalizeMuralStatus, normalizeRipioStatus, planConversion, requiredArsBuffer, settlementPlan };