@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/adapters/stellar/index.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Stellar Adapter for Upshift SDK
+ *
+ * Provides Stellar vault operations: deposit, redeem, position queries,
+ * and on-chain data fetching via Soroban RPC.
+ *
+ * @module StellarAdapter
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StellarAdapter = exports.Stellar = void 0;
+const StellarConstants = __importStar(require("./constants"));
+const StellarGetters = __importStar(require("./getters"));
+const StellarActions = __importStar(require("./actions"));
+const StellarSubmit = __importStar(require("./submit"));
+const utils_1 = require("./utils");
+exports.Stellar = {
+    utils: utils_1.StellarUtils,
+    constants: StellarConstants,
+    actions: StellarActions,
+    submit: StellarSubmit,
+    getters: StellarGetters,
+};
+/**
+ * Stellar Adapter for Upshift SDK
+ *
+ * @example
+ * ```
+ * const adapter = new StellarAdapter('testnet');
+ * const xdr = await adapter.vaultDeposit({
+ *   contractId: 'CBGWW5...',
+ *   amount: '1000000',
+ *   senderAddress: 'GDLZ...',
+ * });
+ * // Sign xdr with wallet (e.g. Freighter), then submit via adapter.submitTransaction()
+ * ```
+ */
+class StellarAdapter {
+    _network;
+    /**
+     * Optional consumer-supplied Soroban RPC endpoint (e.g. a keyed Alchemy URL).
+     * When set it is the primary, with the SDK's public endpoints as failover.
+     */
+    _sorobanRpcUrl;
+    /**
+     * @param network - Stellar network to operate on; defaults to `'mainnet'`.
+     * @param options - Optional adapter configuration. Its `sorobanRpcUrl` field
+     *   overrides the Soroban RPC endpoint (e.g. a keyed Alchemy URL): it becomes
+     *   the primary with the SDK's built-in public endpoints kept behind it as
+     *   failover, and a per-call `sorobanRpcUrl` (on the deposit/redeem params)
+     *   takes precedence over this adapter-level one.
+     */
+    constructor(network = 'mainnet', options) {
+        this._network = network;
+        this._sorobanRpcUrl = options?.sorobanRpcUrl;
+    }
+    get network() {
+        return this._network;
+    }
+    isStellarAddress(address) {
+        return utils_1.StellarUtils.isStellarAddress(address);
+    }
+    getExplorerLink(id, type) {
+        return utils_1.StellarUtils.getExplorerLink({ id, type, network: this._network });
+    }
+    /**
+     * Build an unsigned deposit transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
+    async vaultDeposit(params) {
+        return StellarActions.handleStellarDeposit({
+            ...params,
+            network: this._network,
+            // A per-call override (params.sorobanRpcUrl) wins over the adapter-level one.
+            sorobanRpcUrl: params.sorobanRpcUrl ?? this._sorobanRpcUrl,
+        });
+    }
+    /**
+     * Build an unsigned redeem transaction for a Stellar vault.
+     *
+     * Side effect on failure: a redemption the vault cannot serve is reported to
+     * that vault's curator, since Stellar vaults are instant-redeem only and this
+     * is the curator's only signal. Fire-and-forget — it never delays or alters
+     * the error you receive. On by default in production; see
+     * `monitoring.curatorAlerts` and the Curator Notifications section of the
+     * Stellar Actions guide for exactly what is sent and how to opt out.
+     *
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
+    async vaultRedeem(params) {
+        return StellarActions.handleStellarRedeem({
+            ...params,
+            network: this._network,
+            // A per-call override (params.sorobanRpcUrl) wins over the adapter-level one.
+            sorobanRpcUrl: params.sorobanRpcUrl ?? this._sorobanRpcUrl,
+        });
+    }
+    /**
+     * Side effect: a submitted transaction that the network reports as a failed
+     * `redeem` operation is reported to that vault's curator, on the same
+     * fire-and-forget terms as {@link StellarAdapter.vaultRedeem}.
+     *
+     * Submit a signed Soroban transaction and poll until the network confirms it.
+     *
+     * Submits on the network this adapter was constructed with, so `signedXdr`
+     * must be signed for that same network.
+     *
+     * @param signedXdr - Base64-encoded XDR of the signed transaction.
+     * @returns The transaction hash once the network confirms it as successful.
+     * @throws {@link UpshiftTimeoutError} when the transaction is not confirmed
+     *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+     * @throws {@link UpshiftSDKError} when the RPC rejects the submission or the
+     *   transaction confirms as failed. Its `context` carries `{ network, status }`
+     *   plus, when the result XDR decodes, a `resultCode` string holding the
+     *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+     *   is `undefined` when the code cannot be decoded.
+     * @example
+     * ```ts
+     * try {
+     *   const hash = await adapter.submitTransaction(signedXdr);
+     * } catch (err) {
+     *   if (err instanceof UpshiftSDKError && err.context?.resultCode === 'txBadSeq') {
+     *     // stale sequence number — rebuild the transaction and resubmit
+     *   }
+     * }
+     * ```
+     */
+    async submitTransaction(signedXdr) {
+        return StellarSubmit.submitStellarTransaction(signedXdr, this._network, this._sorobanRpcUrl);
+    }
+    /**
+     * Get user's vault share balance.
+     *
+     * @returns The position `{ shares, decimals, decimalsFromFallback }`, or null
+     * if the balance read fails. When `decimalsFromFallback` is `true` the
+     * `decimals()` read failed and `decimals` is the fallback (7) — callers sizing
+     * a redeem MUST refuse rather than trust it.
+     */
+    async getUserPosition(vaultAddress, walletAddress) {
+        return StellarGetters.getStellarUserPosition(vaultAddress, walletAddress, this._network, this._sorobanRpcUrl);
+    }
+    /**
+     * Preview how many vault shares a deposit amount would yield.
+     * @param vaultAddress  Stellar contract ID (C… address)
+     * @param rawAmount     Deposit amount in the deposit token's smallest unit
+     * @returns Raw share amount as a string, or null if query fails.
+     */
+    async convertToShares(vaultAddress, rawAmount) {
+        return StellarGetters.convertToShares(vaultAddress, rawAmount, this._network, this._sorobanRpcUrl);
+    }
+}
+exports.StellarAdapter = StellarAdapter;
+exports.default = StellarAdapter;
+//# sourceMappingURL=index.js.map

package/lib/adapters/stellar/invocation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Stellar Invocation Decoding
+ *
+ * Reads back what a built transaction actually invokes. `submitStellarTransaction`
+ * takes an opaque signed XDR — it has no idea whether it is broadcasting a
+ * deposit, a redeem, or something else — so a failure there cannot be attributed
+ * to a vault operation without looking inside the envelope.
+ */
+import type { FeeBumpTransaction, Transaction } from '@stellar/stellar-sdk';
+/** A vault contract invocation recovered from a transaction envelope. */
+export interface IVaultInvocation {
+    /** Invoked contract (C-address). */
+    contractId: string;
+    /** Contract function name, e.g. `'redeem'` or `'deposit'`. */
+    functionName: string;
+    /**
+     * First argument as a decimal string, when it decodes to an integer. Both
+     * `deposit(assets, …)` and `redeem(shares, …)` lead with the `i128` amount.
+     * `undefined` when the argument is absent or not an integer.
+     */
+    amountRaw?: string;
+    /**
+     * Second argument as a Stellar address, when it decodes to one — the
+     * `receiver` in both vault signatures. `undefined` otherwise.
+     */
+    receiver?: string;
+    /**
+     * Third argument as a Stellar address, when it decodes to one — `owner` in
+     * `redeem(shares, receiver, owner, operator)`, i.e. the account whose shares
+     * are burned. Identical to `receiver` for the self-redeem the SDK builds, but
+     * they differ for a delegated redemption. `undefined` otherwise.
+     */
+    owner?: string;
+}
+/**
+ * Decode the single Soroban contract invocation in a transaction.
+ *
+ * Every transaction the SDK builds carries exactly one `invokeHostFunction`
+ * operation (see `buildSorobanTx`), so the first one found is authoritative.
+ * Purely local — no RPC, no network.
+ *
+ * Written defensively rather than optimistically: this is called from an error
+ * path where the envelope may be anything a caller handed us, and a throw here
+ * would replace the real transaction failure with a decoding error. Anything
+ * unexpected — a fee-bump wrapper, a classic payment, a shape-drifted SDK
+ * union, a non-address argument — yields `undefined`.
+ *
+ * @param tx - Parsed transaction (e.g. `TransactionBuilder.fromXDR(...)`, whose
+ *   return type includes the fee-bump wrapper — that case yields `undefined`,
+ *   since the invocation lives in the inner transaction and the SDK never
+ *   builds one).
+ * @returns The invocation, or `undefined` when the transaction does not carry a
+ *   decodable contract call.
+ */
+export declare function describeVaultInvocation(tx: Transaction | FeeBumpTransaction): IVaultInvocation | undefined;

package/lib/adapters/stellar/invocation.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Stellar Invocation Decoding
+ *
+ * Reads back what a built transaction actually invokes. `submitStellarTransaction`
+ * takes an opaque signed XDR — it has no idea whether it is broadcasting a
+ * deposit, a redeem, or something else — so a failure there cannot be attributed
+ * to a vault operation without looking inside the envelope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeVaultInvocation = describeVaultInvocation;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+/**
+ * Decode the single Soroban contract invocation in a transaction.
+ *
+ * Every transaction the SDK builds carries exactly one `invokeHostFunction`
+ * operation (see `buildSorobanTx`), so the first one found is authoritative.
+ * Purely local — no RPC, no network.
+ *
+ * Written defensively rather than optimistically: this is called from an error
+ * path where the envelope may be anything a caller handed us, and a throw here
+ * would replace the real transaction failure with a decoding error. Anything
+ * unexpected — a fee-bump wrapper, a classic payment, a shape-drifted SDK
+ * union, a non-address argument — yields `undefined`.
+ *
+ * @param tx - Parsed transaction (e.g. `TransactionBuilder.fromXDR(...)`, whose
+ *   return type includes the fee-bump wrapper — that case yields `undefined`,
+ *   since the invocation lives in the inner transaction and the SDK never
+ *   builds one).
+ * @returns The invocation, or `undefined` when the transaction does not carry a
+ *   decodable contract call.
+ */
+function describeVaultInvocation(tx) {
+    try {
+        if (!('operations' in tx))
+            return undefined;
+        for (const op of tx.operations ?? []) {
+            if (op.type !== 'invokeHostFunction')
+                continue;
+            const hostFn = op.func;
+            if (hostFn.switch() !==
+                stellar_sdk_1.xdr.HostFunctionType.hostFunctionTypeInvokeContract()) {
+                continue;
+            }
+            const invocation = hostFn.invokeContract();
+            const contractId = stellar_sdk_1.Address.fromScAddress(invocation.contractAddress()).toString();
+            const functionName = invocation.functionName().toString();
+            const args = invocation.args();
+            return {
+                contractId,
+                functionName,
+                amountRaw: decodeInteger(args[0]),
+                receiver: decodeAddress(args[1]),
+                owner: decodeAddress(args[2]),
+            };
+        }
+    }
+    catch {
+        // Shape drift or an envelope we don't recognise. The caller falls back to
+        // reporting nothing rather than misattributing the failure.
+    }
+    return undefined;
+}
+/** `bigint` / `number` ScVal → decimal string; `undefined` for anything else. */
+function decodeInteger(value) {
+    if (!value)
+        return undefined;
+    try {
+        const native = (0, stellar_sdk_1.scValToNative)(value);
+        if (typeof native === 'bigint')
+            return native.toString();
+        if (typeof native === 'number' && Number.isInteger(native)) {
+            return String(native);
+        }
+    }
+    catch {
+        // Not an integer ScVal.
+    }
+    return undefined;
+}
+/** Address ScVal → strkey; `undefined` for anything else. */
+function decodeAddress(value) {
+    if (!value)
+        return undefined;
+    try {
+        return stellar_sdk_1.Address.fromScVal(value).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=invocation.js.map

package/lib/adapters/stellar/soroban.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
+import { type xdr, rpc } from '@stellar/stellar-sdk';
+import type { IStellarNetwork } from './types';
+/** Resolved network configuration for Soroban RPC calls. */
+export interface ISorobanNetworkConfig {
+    /** Primary endpoint — the first of {@link rpcUrls}; kept for convenience. */
+    rpcUrl: string;
+    /** Ordered endpoints for health-gated failover: primary first, fallbacks after. */
+    rpcUrls: readonly string[];
+    passphrase: string;
+}
+export declare function createServer(rpcUrl: string): rpc.Server;
+/**
+ * Resolve the ordered RPC endpoints and network passphrase for a Stellar network.
+ *
+ * When `overrideRpcUrl` is supplied (e.g. a consumer's keyed Alchemy endpoint),
+ * it becomes the primary with the built-in public endpoints kept behind it as
+ * failover — so opting into a premium provider still degrades to the public
+ * network rather than becoming a new single point of failure. The endpoint is
+ * injected rather than hardcoded, so the adapter depends on configuration, not a
+ * constant.
+ */
+export declare function resolveNetworkConfig(network: IStellarNetwork, overrideRpcUrl?: string): ISorobanNetworkConfig;
+/**
+ * Clear the health-check cache and any in-flight probes. Test-only seam.
+ * @internal
+ */
+export declare function resetHealthyServerCache(): void;
+/**
+ * Host-only view of an RPC URL, safe for logs. Keyed provider endpoints put the
+ * API key in the path (e.g. Alchemy `/v2/<key>`), so logging the raw URL would
+ * leak the secret into SDK logs / crash reporters. Returns just protocol+host.
+ * @internal
+ */
+export declare function redactRpcUrl(url: string): string;
+/**
+ * Return a Soroban RPC server backed by a healthy endpoint for `config`. Thin
+ * wrapper over {@link resolveHealthyServer} for callers (e.g. submission) that
+ * only need the server, not the URL it resolved to.
+ *
+ * @internal
+ */
+export declare function getHealthyServer(config: ISorobanNetworkConfig): Promise<rpc.Server>;
+/**
+ * A thrown RPC error is retryable on another endpoint UNLESS it is one of our
+ * typed domain errors. Those mark a *deterministic* outcome — a contract revert,
+ * an unfunded account, archived state needing restore, a bad input, or a local
+ * assembly failure — which reproduces identically on every node, so retrying
+ * elsewhere only wastes calls. Any other throw (a transport hang/reset, or a
+ * method-specific node error from an endpoint that still answered `getHealth()`)
+ * is worth the next endpoint.
+ *
+ * Exported so an operation with different semantics (e.g. an idempotency-aware
+ * submission path) can compose or replace this policy via
+ * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
+ * @internal
+ */
+export declare function isRetryableSorobanRpcError(err: unknown): boolean;
+/**
+ * Whether a simulation *error* string is a node/infrastructure failure (which
+ * clears on another endpoint) rather than a genuine contract revert (which
+ * reproduces on every node). `isSimulationError` alone can't tell these apart —
+ * both arrive as a populated `error` field — so callers use this to decide
+ * whether to fail over or treat the error as terminal.
+ * @internal
+ */
+export declare function isRetryableSimulationError(errorText: string): boolean;
+/**
+ * Tunables for {@link withEndpointFailover}, injected with sensible defaults so
+ * a new operation can vary retry policy or latency budget without editing the
+ * failover core (Open/Closed at the call site).
+ */
+export interface FailoverOptions {
+    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableSorobanRpcError}. */
+    isRetryable?: (err: unknown) => boolean;
+    /** Per-attempt timeout in ms. Defaults to {@link RPC_OPERATION_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Run an idempotent, side-effect-free `operation` (a read or a tx build) against
+ * a Soroban endpoint, failing over to the remaining endpoints on a retryable
+ * failure.
+ *
+ * {@link getHealthyServer} only proves an endpoint answered `getHealth()`, and
+ * caches that choice for {@link HEALTHY_SERVER_TTL_MS} — but the node can still
+ * hang or return a method-specific error on the *real* call. So we run the op on
+ * the health-gated server first (the fast, cached path) and, on a retryable
+ * failure, drop that cached choice and retry the op against every endpoint in
+ * priority order. Deterministic contract/domain errors short-circuit (see
+ * {@link isRetryableSorobanRpcError}); each attempt is time-boxed so a hung node can't
+ * stall the loop.
+ *
+ * The `operation` is a strategy (dependency-injected), so new read/build calls
+ * reuse this failover without changing it; `options` keeps retry policy and
+ * timeout open for extension. Submission is deliberately NOT routed through here
+ * — re-sending a signed transaction across endpoints risks a double-submit, so
+ * it needs sequence/DUPLICATE-based idempotency rather than blind retry.
+ * @internal
+ */
+export declare function withEndpointFailover<T>(config: ISorobanNetworkConfig, method: string, operation: (server: rpc.Server) => Promise<T>, options?: FailoverOptions): Promise<T>;
+/**
+ * Validate and convert a string amount to a non-negative BigInt.
+ * Throws a descriptive error if the value is not a valid non-negative integer string.
+ */
+export declare function toBigIntAmount(value: string, label: string): bigint;
+export declare function queryContract(config: ISorobanNetworkConfig, contractId: string, method: string, args?: xdr.ScVal[]): Promise<xdr.ScVal | null>;
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ *
+ * Thrown errors carry `context.stage` naming where the build broke:
+ * `'simulation'` (the contract itself rejected the call), `'restore-required'`,
+ * `'assembly'`, or `'rpc-failover'` (no endpoint answered). Callers use it to
+ * separate a vault-level rejection from a transport problem — see the curator
+ * alerting in `handleStellarRedeem`. Validation errors (e.g.
+ * `ACCOUNT_NOT_FUNDED`) carry no stage, so treat a missing one as "not a
+ * vault-level failure" rather than assuming the field is always present.
+ */
+export declare function buildSorobanTx(config: ISorobanNetworkConfig, sourceAddress: string, contractId: string, method: string, args: xdr.ScVal[]): Promise<string>;