@augustdigital/sdk 9.7.1 → 9.9.0

package/lib/modules/vaults/main.js

@@ -1188,6 +1188,29 @@ class AugustVaults extends core_1.AugustBase {
             fromBlock: options?.fromBlock,
         });
     }
+    /**
+     * Read a SwapRouter origin code's on-chain registration through this
+     * instance's provider for `chainId`. See {@link getOriginInfo} for the
+     * registration rule and caching.
+     *
+     * @param options - `chainId` and the `bytes32` `originCode` to look up.
+     * @returns {@link IOriginInfo}.
+     * @throws AugustValidationError (`INVALID_CHAIN`) when no provider is
+     *   configured for `chainId`; (`INVALID_INPUT`) for a malformed code.
+     * @throws AugustSDKError when the `origins(bytes32)` read fails.
+     * @worstCaseRpcCalls 1 — one `origins(bytes32)` read, cached for 5 minutes.
+     * @example
+     * ```ts
+     * const info = await augustSdk.getOriginInfo({ chainId: 1, originCode });
+     * ```
+     */
+    async getOriginInfo(options) {
+        (0, core_1.assertEvmProviderConfigured)(options.chainId, this.providers, 'getOriginInfo');
+        return (0, core_1.getOriginInfo)({
+            ...options,
+            rpcUrl: this.providers[options.chainId],
+        });
+    }
     /**
      * @function getStakingPositions gets all available reward staking positions
      * @param wallet optionally passed user wallet address

package/lib/modules/vaults/write.actions.d.ts

@@ -1,5 +1,5 @@
 import { type Signer, type Wallet, type TransactionResponse } from 'ethers';
-import type { IAddress } from '../../types';
+import { type IAddress } from '../../types';
 import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions, ISwapRouterDepositOptions } from '../../types';
 export type IContractWriteOptions = {
     target: IAddress;
@@ -28,15 +28,13 @@ export type IContractWriteOptions = {
      */
     isDepositWithPermit?: boolean;
     /**
-     * Optional: address that receives the vault shares. Defaults to `wallet`.
-     * Only honored on the SwapRouter dispatch path; legacy adapters mint to `wallet`.
+     * @deprecated Ignored — `vaultDeposit` mints to `wallet`. Use
+     * {@link swapRouterDeposit}'s `receiver` instead.
      */
     receiver?: IAddress;
     /**
-     * Optional: slippage tolerance in bps (1 bp = 0.01%) applied to any swap
-     * quote the SwapRouter dispatch path fetches when `depositAsset` differs
-     * from the vault's reference asset. Must be in `[0, 10_000)`. Defaults to
-     * `100` (1%). Ignored for same-asset deposits and legacy adapter paths.
+     * @deprecated Ignored — `vaultDeposit` never swaps. Use
+     * {@link swapRouterDeposit}'s `slippageBps` instead.
      */
     slippageBps?: number;
 };
@@ -171,18 +169,76 @@ export type ApproveResult =
  | {
     kind: 'native';
 };
+/**
+ * Why {@link getDepositRoute} kept a deposit on the vault's native path.
+ * `no-origin-code` is what every SDK without `attribution.originCode` gets.
+ */
+export type DepositRouteReason = 'no-origin-code' | 'no-router' | 'chain-not-supported' | 'permit' | 'native-token' | 'adapter' | 'vault-not-registered' | 'asset-not-accepted' | 'router-token-not-whitelisted' | 'origin-not-registered';
+/** A deposit's route — the SwapRouter or the vault's native path — and the address to approve. */
+export type IDepositRoute = {
+    /**
+     * `router`: `SwapRouter.deposit` carrying the instance origin code (a direct
+     * deposit, never a swap). `native`: the vault's own deposit path.
+     */
+    via: 'native' | 'router';
+    /** Address to approve for the deposit token; `null` for a native-token deposit (`msg.value`). */
+    spender: IAddress | null;
+    /** Why the deposit stays native; absent on the router route. */
+    reason?: DepositRouteReason;
+};
+/** Options for {@link getDepositRoute} — the same fields `vaultDeposit` reads. */
+export type IGetDepositRouteOptions = Pick<IContractWriteOptions, 'target' | 'depositAsset' | 'chainId' | 'isDepositWithPermit'>;
+/**
+ * Resolve whether a deposit can go through the SwapRouter carrying the
+ * instance origin code (`router`) or takes the vault's native path
+ * (`native`), and which address to approve. Read-only. `vaultDeposit` and
+ * `approve` follow this route, so integrators that manage approvals
+ * themselves must approve `route.spender`, not the vault.
+ *
+ * The route is `router` only when an origin code is configured, the chain is
+ * Ethereum mainnet ({@link ORIGIN_ATTRIBUTION_CHAINS}) and has a SwapRouter,
+ * the vault is registered on it, the vault accepts the asset directly (its
+ * reference asset, or a Tokenized Vault V2 whitelisted asset — deposited
+ * as-is, never swapped), the router whitelists the asset, the deposit is not a
+ * permit, native-token or adapter deposit, and the code is registered.
+ * Otherwise it is `native` with a `reason`.
+ *
+ * @param signer - ethers `Signer` / `Wallet` used for the reads.
+ * @param options - {@link IGetDepositRouteOptions}; `depositAsset` defaults
+ *   to the vault's underlying.
+ * @returns {@link IDepositRoute}.
+ * @throws AugustValidationError on an invalid `target`, or an unregistered
+ *   code under `attribution.strictOrigin`.
+ * @throws AugustSDKError when a backend, vault or router read fails.
+ * @worstCaseRpcCalls 7 — the backend vault row, `asset()`, the router's
+ *   `vaultInfo`, the vault's `assetsWhitelistAddress()` and
+ *   `getWhitelistedAssets()` (Tokenized Vault V2 non-reference asset only),
+ *   the router's `whitelistedTokens(asset)`, and the router's `origins`. The
+ *   router reads and `getWhitelistedAssets()` are cached for 5 minutes. No
+ *   router read without a code or off Ethereum mainnet.
+ * @example
+ * ```ts
+ * const route = await augustSdk.evm.getDepositRoute({ target: vault, depositAsset: usdt });
+ * if (route.spender) await approveToken(usdt, route.spender, amount);
+ * ```
+ */
+export declare function getDepositRoute(signer: Signer | Wallet, options: IGetDepositRouteOptions): Promise<IDepositRoute>;
 /**
  * Approve a vault (or the appropriate adapter wrapper) to spend a token
  * ahead of a separate deposit call. Spender routing mirrors
  * {@link vaultDeposit} (multi-asset → vault, adapter → wrapper, standard →
- * vault). Returns `undefined` when the existing allowance already covers
- * `amount` **or** when the deposit asset is native.
+ * vault, SwapRouter when {@link getDepositRoute} routes there). Returns
+ * `undefined` when the existing allowance already covers `amount` **or**
+ * when the deposit asset is native.
  *
  * @returns Transaction hash when an approval was sent, `undefined` when
  *   the existing allowance already covers `amount` or the deposit asset is
  *   native (no ERC-20 allowance applies). Use {@link approve} for a
  *   discriminated `ApproveResult` if you need to tell those two cases apart.
  * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter (the spender
+ *   follows {@link getDepositRoute}).
  *
  * @example
  * ```ts
@@ -225,6 +281,9 @@ export declare function vaultApprove(signer: Signer | Wallet, options: IContract
  * ```
  *
  * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter (the spender
+ *   follows {@link getDepositRoute}).
  * @throws AugustSDKError when the approval submission fails.
  */
 export declare function approve(signer: Signer | Wallet, options: IContractWriteOptions): Promise<ApproveResult>;
@@ -234,6 +293,11 @@ export declare function approve(signer: Signer | Wallet, options: IContractWrite
  * Paraswap adapter, native-token wrapper, depositWithPermit) based on the
  * vault version and `depositAsset`.
  *
+ * With `attribution.originCode` configured, a deposit the SwapRouter can take
+ * directly goes through `SwapRouter.deposit` carrying that code, and the
+ * router is approved instead of the vault — see {@link getDepositRoute} for
+ * the rules and the fallback reasons. Without a code nothing changes.
+ *
  * Amounts are encoded against the **deposit token's** decimals, not the
  * vault's share decimals. The SDK reads the appropriate decimals via the
  * vault metadata and the asset's ERC-20.
@@ -249,6 +313,8 @@ export declare function approve(signer: Signer | Wallet, options: IContractWrite
  * @returns Deposit transaction hash.
  * @throws AugustValidationError on invalid wallet/target/amount or missing
  *   adapter config when `depositAsset` differs from the vault underlying.
+ * @throws AugustValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter.
  * @throws AugustSDKError when the deposit submission or on-chain call fails.
  *
  * @example
@@ -486,7 +552,9 @@ export declare function rwaRedeemAsset(signer: Signer | Wallet, options: IRwaRed
  * @returns The transaction hash of the `swapAndDeposit` call.
  *
  * @throws {@link AugustValidationError} for unsupported chains, invalid
- * addresses, empty/oversized swap arrays.
+ * addresses, empty/oversized swap arrays, or an origin code not registered on
+ * the router (a per-call code, or the instance code under
+ * `attribution.strictOrigin`), before any approval.
  * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
  *
  * @example
@@ -526,7 +594,11 @@ export declare function swapAndDeposit(signer: Signer | Wallet, options: ISwapAn
  * @returns The transaction hash of the `deposit` call.
  *
  * @throws {@link AugustValidationError} for unsupported chains, invalid
- * addresses, or zero amount.
+ * addresses, zero amount, or an origin code not registered on the router (a
+ * per-call code, or the instance code under `attribution.strictOrigin`),
+ * before any approval; with code `ACCOUNT_NOT_FUNDED` when the account cannot
+ * cover gas.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
  */
 export declare function depositViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterDirectDepositOptions): Promise<string>;
 /**
@@ -550,7 +622,11 @@ export declare function depositViaSwapRouter(signer: Signer | Wallet, options: I
  * @returns The transaction hash of the `depositNativeToken` call.
  *
  * @throws {@link AugustValidationError} for unsupported chains, invalid
- * addresses, or zero amount.
+ * addresses, zero amount, or an origin code not registered on the router (a
+ * per-call code, or the instance code under `attribution.strictOrigin`),
+ * before any approval; with code `ACCOUNT_NOT_FUNDED` when the account cannot
+ * cover gas.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
  */
 export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterNativeDepositOptions): Promise<string>;
 /**
@@ -600,21 +676,22 @@ export declare function isNativeSwapRouterDepositSupported(chainId: number, vaul
 }): Promise<boolean>;
 /**
  * Deposit into an August vault through the on-chain `SwapRouter`, selecting the
- * correct router path from the deposit asset. This is the high-level, explicit
- * counterpart to the SwapRouter branch inside {@link vaultDeposit}.
+ * correct router path from the deposit asset.
  *
- * Where `vaultDeposit` decides whether to use the SwapRouter from the
- * `VAULTS_USING_SWAP_ROUTER` allowlist, this function always routes through the
- * SwapRouter because the caller asked it to. Making the intent explicit is the
+ * {@link vaultDeposit} never swaps; this function always routes through the
+ * SwapRouter, because the caller asked it to. Keeping swaps opt-in is the
  * point: a native-deposit vault (e.g. a multi-asset Tokenized Vault V2 whose
  * non-reference assets are accepted directly) is never accidentally swapped —
- * the regression that implicit, allowlist-driven routing caused. Use
- * `vaultDeposit` for native / adapter deposits and this for SwapRouter deposits.
+ * the regression that implicit, allowlist-driven routing inside `vaultDeposit`
+ * caused before it was removed. Use `vaultDeposit` for native / adapter
+ * deposits and this for SwapRouter deposits.
  *
  * The vault's reference asset and its decimals are read on-chain (never trusted
  * from the caller — a wrong reference asset would mis-route the swap). The path
  * is then chosen from `depositAsset`:
- *  - equals the reference asset → direct router deposit, no swap
+ *  - equals the reference asset, or is an asset a Tokenized Vault V2 accepts
+ *    as-is that the router also whitelists (e.g. USDT into Sentora USD) →
+ *    direct router deposit, no swap and no swap fee
  *    ({@link depositViaSwapRouter});
  *  - the zero address → native-token deposit ({@link depositNativeViaSwapRouter}),
  *    valid only when the reference asset is the chain's wrapped-native token —
@@ -625,23 +702,36 @@ export declare function isNativeSwapRouterDepositSupported(chainId: number, vaul
  *    the chain's whitelisted aggregator, fail-closed on router/selector drift)
  *    bundled into {@link swapAndDeposit}.
  *
- * An `originCode` is forwarded verbatim to whichever of those three entry points
- * runs, so a partner's origin fee accrues on every path. Omitting it sends the
- * all-zero sentinel, which the router reads as "no origin fee".
+ * The origin code — the per-call `originCode`, else the SDK instance's
+ * `attribution.originCode` on Ethereum mainnet, else the all-zero sentinel
+ * ("no origin fee") — is forwarded to whichever of those three entry points
+ * runs, so a partner's origin fee accrues on every path.
  *
  * Side effects: reads tokenized-vault metadata, the vault's reference asset and
- * decimals, and (on the swap path) one Paraswap quote; sends one ERC-20
- * `approve` to the SwapRouter when allowance is short, then the deposit tx.
+ * decimals, for a Tokenized Vault V2 non-reference asset the router's
+ * `vaultInfo` and `whitelistedTokens` and the vault's assets whitelist, the
+ * origin code's registration, and (on the swap path) one Paraswap quote;
+ * sends one ERC-20 `approve` to the SwapRouter when allowance is short, then
+ * the deposit tx.
  *
  * @param signer - ethers `Signer` or `Wallet` that signs the approval + deposit.
  * @param options - {@link ISwapRouterDepositOptions}.
  * @returns The transaction hash of the router deposit call.
  * @throws {@link AugustValidationError} for an unsupported chain (no SwapRouter
  *   deployment), an invalid vault or deposit-asset address, a missing or zero
- *   amount, a native deposit into a non-wrapped-native vault, or drift between
- *   the aggregator quote and the on-chain router whitelist.
- * @worstCaseRpcCalls 5 on the swap path — tokenized-vault metadata, reference
- *   asset + decimals, deposit-token decimals, the quote, and the allowance read.
+ *   amount, a native deposit into a non-wrapped-native vault, drift between
+ *   the aggregator quote and the on-chain router whitelist, or an origin code
+ *   not registered on the router (a per-call code, or the instance code under
+ *   `attribution.strictOrigin`), before any approval; with code
+ *   `ACCOUNT_NOT_FUNDED` when the account cannot cover gas.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ * @worstCaseRpcCalls 10 on the swap path into a Tokenized Vault V2 —
+ *   tokenized-vault metadata, reference asset + decimals, deposit-token
+ *   decimals, the router's `vaultInfo` and `whitelistedTokens`, the vault's
+ *   `assetsWhitelistAddress()` and `getWhitelistedAssets()`, the quote, the
+ *   origin code's `origins` (none for the zero sentinel), and the allowance
+ *   read. The router reads and `getWhitelistedAssets()` are cached for 5
+ *   minutes.
  * @example
  * ```ts
  * // USDT deposited into a USDC-reference vault → swapped to USDC en route.