@ember-finance/sdk 2.10.4 → 2.11.0-pre.1

package/dist/src/placements/types.d.ts

@@ -0,0 +1,139 @@
+import { ChainType } from "../common/constants.js";
+/** Identifier for a protocol adapter, e.g. "bluefin-spot". */
+export type ProtocolId = string;
+export interface ChainRef {
+    type: ChainType;
+    /** EVM network id. Absent on chains that have none. */
+    chainId?: number;
+    /** Chain identifier, e.g. "sui-mainnet". */
+    identifier?: string;
+}
+/** An Ember vault receipt coin, as listed by the vaults API. */
+export interface ReceiptCoin {
+    /** Sui coin type, or EVM token address. */
+    coin: string;
+    chain: ChainRef;
+    decimals: number;
+    symbol?: string;
+    /** Display name of the vault this coin belongs to. */
+    vault?: string;
+    /** RPC endpoint for this coin's chain, when one is published. */
+    rpcUrl?: string;
+}
+export type PointerOrigin = "Registry" | "Manual";
+/** Somewhere a receipt coin is listed. Carries no amount. */
+export interface PlacementRef {
+    protocol: ProtocolId;
+    chain: ChainRef;
+    /** Pool, market or vault address. */
+    venue: string;
+    coin: string;
+    /** Decimals of `coin`. */
+    decimals: number;
+    /**
+     * The protocol's display name, e.g. "Current Finance". Absent when the
+     * vaults API has no catalogue entry — render `protocol` then.
+     */
+    protocolName?: string;
+    /** Icon for the protocol, when one is catalogued. */
+    protocolLogoUrl?: string;
+    source: PointerOrigin;
+    /** Human-readable venue name, for display only. */
+    label?: string;
+    /**
+     * The token an account holds for its position here, when that is not the
+     * venue itself. Defaults to `venue`.
+     */
+    shareToken?: string;
+    /** Deep link to the venue, for the caller to render. */
+    url?: string;
+    /**
+     * RPC endpoint for this chain, when one is published. Absent means fall
+     * back to whatever the reader was configured with.
+     */
+    rpcUrl?: string;
+}
+/** A resolved pointer: what one account holds there. */
+export interface Placement extends PlacementRef {
+    /** The account's own position, in base units of `coin`. */
+    amount: string;
+    readAt: string;
+}
+export interface PlacementFailure {
+    protocol: ProtocolId;
+    stage: "discover" | "read";
+    coin?: string;
+    reason: string;
+}
+/**
+ * One vault's shares for one account.
+ *
+ * A non-empty `failures` means `placements` is incomplete — a caller showing a
+ * total should say so rather than quietly under-report.
+ */
+export interface AccountShares {
+    vaultId: string;
+    coin: ReceiptCoin;
+    /** Held in the account's own wallet. Base units of `coin`. */
+    available: string;
+    /** Wrapped into a cover vault. Absent when the vault is not covered. */
+    covered?: string;
+    placements: Placement[];
+    failures: PlacementFailure[];
+}
+export interface SuiObjectContents {
+    address: string;
+    type: string;
+    json: Record<string, unknown>;
+}
+export interface SuiDynamicField {
+    name: unknown;
+    valueType: string;
+    value: unknown;
+}
+/** Narrow read port over Sui, so a caller can supply its own transport. */
+export interface SuiReader {
+    objects(ids: string[]): Promise<Record<string, SuiObjectContents>>;
+    dynamicFields(parentId: string, limit?: number): Promise<SuiDynamicField[]>;
+    /**
+     * One dynamic field addressed by its BCS-encoded key. Resolves to undefined
+     * when the key is absent.
+     */
+    dynamicField(parentId: string, key: {
+        type: string;
+        bcs: string;
+    }): Promise<unknown | undefined>;
+    /** Total balance an address holds of one coin type, in base units. */
+    balance(owner: string, coinType: string): Promise<string>;
+    /** Objects of one type owned by an address. */
+    ownedObjects(owner: string, type: string): Promise<SuiObjectContents[]>;
+}
+/** Narrow read port over EVM: one `eth_call` is all these reads need. */
+export interface EvmReader {
+    /** `endpoint`, when given, overrides whatever the reader is configured with. */
+    call(chainId: number, to: string, data: string, endpoint?: string): Promise<string>;
+}
+/** Where pointers come from. */
+export interface PointerSource {
+    placements(protocol: ProtocolId, coin: ReceiptCoin): Promise<PlacementRef[]>;
+}
+/** Resolves a vault to the receipt coins it issues, one per chain it runs on. */
+export interface VaultCoinsResolver {
+    coinsForVault(vaultId: string): Promise<ReceiptCoin[]>;
+    coverVault?(coin: ReceiptCoin): Promise<string | undefined>;
+}
+export interface PlacementsContext {
+    sui?: SuiReader;
+    evm?: EvmReader;
+    pointers: PointerSource;
+    vaults?: VaultCoinsResolver;
+}
+/** The extension seam. One protocol, registered with `registerAdapter`. */
+export interface ProtocolAdapter {
+    readonly id: ProtocolId;
+    readonly chain: ChainType;
+    /** Pointers only, carrying no amounts. */
+    discover(coin: ReceiptCoin, ctx: PlacementsContext): Promise<PlacementRef[]>;
+    /** What `account` holds at each venue, in base units of `ref.coin`. */
+    read(refs: PlacementRef[], account: string, ctx: PlacementsContext): Promise<Placement[]>;
+}

package/dist/src/placements/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/placements/vaults.d.ts

@@ -0,0 +1,15 @@
+import { PlatformEnv } from "../common/constants.js";
+import { VaultCoinsResolver } from "./types.js";
+export interface HttpVaultCoinsOptions {
+    /** Vaults API environment. Defaults to prod. */
+    env?: PlatformEnv;
+    /** Overrides `env` entirely. For a local deployment, or a proxy. */
+    baseUrl?: string;
+}
+/**
+ * Resolves a vault to the receipt coins it issues, from the vaults API.
+ *
+ * A vault runs on one or more chains and issues a distinct receipt coin on
+ * each, so this returns one entry per chain rather than assuming a single coin.
+ */
+export declare function httpVaultCoinsResolver(options?: HttpVaultCoinsOptions): VaultCoinsResolver;

package/dist/src/placements/vaults.js

@@ -0,0 +1,97 @@
+import { environmentConfig } from "../common/constants.js";
+/**
+ * Resolves a vault to the receipt coins it issues, from the vaults API.
+ *
+ * A vault runs on one or more chains and issues a distinct receipt coin on
+ * each, so this returns one entry per chain rather than assuming a single coin.
+ */
+export function httpVaultCoinsResolver(options = {}) {
+    const baseUrl = (options.baseUrl ?? environmentConfig[options.env ?? "prod"].apiHost).replace(/\/$/, "");
+    const get = async (path) => {
+        const response = await fetch(`${baseUrl}${path}`, {
+            headers: { Accept: "application/json" }
+        });
+        if (!response.ok)
+            throw new Error(`vaults api ${response.status} for ${path}`);
+        return (await response.json());
+    };
+    // The chain catalogue is what carries the EVM network id. Without it an EVM
+    // coin has no chainId, and every read for it fails rather than returning a
+    // balance — so this is fetched once and shared, not guessed per coin.
+    let chains;
+    const chainRefs = () => {
+        if (chains)
+            return chains;
+        chains = get("/api/v2/vaults/supported-chains").then(supported => {
+            const byIdentifier = new Map();
+            for (const chain of supported) {
+                if (!chain.identifier)
+                    continue;
+                byIdentifier.set(chain.identifier.toLowerCase(), {
+                    type: chain.type?.toUpperCase() === "SUI" ? "sui" : "evm",
+                    chainId: chain.networkId,
+                    identifier: chain.identifier,
+                    rpcUrl: chain.publicRpcUrl
+                });
+            }
+            return byIdentifier;
+        });
+        // Cache the value, not the rejection: one transient 502 here would
+        // otherwise fail every later call on this resolver for good.
+        chains.catch(() => {
+            chains = undefined;
+        });
+        return chains;
+    };
+    /** Falls back to the identifier's shape when the catalogue has no entry. */
+    const chainRefFor = (identifier, catalogue) => catalogue.get(identifier.toLowerCase()) ?? {
+        type: identifier.toLowerCase().startsWith("sui") ? "sui" : "evm",
+        identifier
+    };
+    return {
+        async coinsForVault(vaultId) {
+            const [vaults, catalogue] = await Promise.all([
+                get(`/api/v2/vaults?vaultId=${encodeURIComponent(vaultId)}`),
+                chainRefs()
+            ]);
+            const list = Array.isArray(vaults) ? vaults : [vaults];
+            const vault = list.find(v => v.id === vaultId) ?? list[0];
+            if (!vault)
+                throw new Error(`vault ${vaultId} not found`);
+            // An ATOMIC vault has no receipt token, but the API still fills
+            // receiptCoin with a placeholder so the field never breaks older
+            // consumers. Reading it would hand back a coin that does not exist.
+            if (vault.vaultType === "ATOMIC") {
+                throw new Error(`vault ${vaultId} is atomic and issues no receipt coin`);
+            }
+            const coins = [];
+            for (const [identifier, details] of Object.entries(vault.detailsByChain ?? {})) {
+                const receipt = details.receiptCoin;
+                if (!receipt?.address)
+                    continue;
+                if (typeof receipt.decimals !== "number") {
+                    throw new Error(`${receipt.address} has no decimals`);
+                }
+                const { rpcUrl, ...chain } = chainRefFor(details.chainIdentifier ?? identifier, catalogue);
+                coins.push({
+                    coin: receipt.address,
+                    chain,
+                    decimals: receipt.decimals,
+                    // The wallet balance is not a placement, so it has no
+                    // pointer to borrow an endpoint from. Carry the published
+                    // one here or the caller must configure every chain itself.
+                    rpcUrl,
+                    symbol: receipt.symbol,
+                    // longName is empty on every vault the API returns
+                    // today, and "" is not nullish — ?? would keep it and
+                    // hand the caller a blank name to render.
+                    vault: vault.longName || vault.name
+                });
+            }
+            if (coins.length === 0) {
+                throw new Error(`vault ${vaultId} issues no receipt coin`);
+            }
+            return coins;
+        }
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ember-finance/sdk",
     "description": "Ember Protocol SDK",
-    "version": "2.10.4",
+    "version": "2.11.0-pre.1",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",
@@ -44,6 +44,11 @@
             "import": "./dist/src/common/index.js",
             "default": "./dist/src/common/index.js"
         },
+        "./placements": {
+            "types": "./dist/src/placements/index.d.ts",
+            "import": "./dist/src/placements/index.js",
+            "default": "./dist/src/placements/index.js"
+        },
         "./abis": {
             "types": "./dist/src/abis/index.d.ts",
             "import": "./dist/src/abis/index.js",