@augustdigital/sdk 9.8.0 → 9.9.1

package/README.md

@@ -82,6 +82,63 @@ new AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });
 new AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });
 ```
 
+### Origin-Code Attribution (SwapRouter)
+
+An integrator with an origin (referral / fee-sharing) code registered on the SwapRouter sets it once on the
+SDK instance. Deposits made through the SDK then carry it on-chain:
+
+```typescript
+const sdk = new AugustSDK({
+  appName: 'acme-trader',
+  providers: { 1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY' },
+  attribution: {
+    originCode: '0x…', // bytes32 registered on the SwapRouter with addOrigin
+    strictOrigin: false, // optional: true throws instead of falling back
+  },
+});
+
+// Check the code before you ship it.
+const { registered, originFeeBps, collector } = await sdk.getOriginInfo({
+  chainId: 1,
+  originCode: '0x…',
+});
+```
+
+- **Ethereum mainnet only.** The instance code is sent on chain 1 (`ORIGIN_ATTRIBUTION_CHAINS`) and on no other
+  chain, even where a SwapRouter is configured.
+- **Where it applies.** `vaultDeposit` sends a deposit through `SwapRouter.deposit` with the code when
+  `sdk.evm.getDepositRoute()` returns `via: 'router'`: the vault is registered on the router, the vault accepts
+  the asset as-is (its reference asset, or a Tokenized Vault V2 whitelisted asset — never swapped), the router
+  whitelists the asset, the deposit is not a permit, native-token or adapter deposit, and the code is
+  registered. `swapRouterDeposit`, `swapAndDeposit`, `depositViaSwapRouter` and `depositNativeViaSwapRouter`
+  send it too.
+- **Precedence.** An `originCode` passed to a router method wins, then the instance code, then the all-zero
+  sentinel (no origin fee). Pass the zero sentinel to opt one call out.
+- **Fallback.** When the code cannot be applied — it is not registered, the chain is not mainnet, the router
+  does not whitelist the asset, the vault does not accept it or is not registered on the router, or it is a
+  permit, native-token or adapter deposit — `vaultDeposit` takes the vault's native path and logs
+  `vaultDeposit:attribution-skipped` with the reason (Sentry tag `sdk.attribution.origin=skipped`). The router
+  methods send the zero sentinel for an unregistered instance code and log `<method>:attribution-skipped`.
+  With `strictOrigin: true` an unregistered instance code throws `AugustValidationError` before any approval
+  instead. An `originCode` passed to a router method that is not registered always throws
+  `AugustValidationError` before any approval.
+- **Approve `route.spender`, not the vault.** A routed deposit is pulled by the SwapRouter. `vaultDeposit` and
+  `approve` handle this; if you send approvals yourself, read the spender first:
+
+  ```typescript
+  const route = await sdk.evm.getDepositRoute({ target: vault, depositAsset: usdc });
+  // route.spender is the SwapRouter when route.via === 'router', else the vault (or adapter wrapper)
+  ```
+
+- **Gas.** Measured on a mainnet fork (repeat 1,000 USDC deposits into Core USDC): direct deposit 102,067 gas;
+  router with a 0% code 161,744 (+59.7k); router with a 1% code 173,135 (+71.1k). A routed deposit also needs a
+  one-time approval of the router per token.
+- **Zero-fee codes.** A code registered with a 0 bps fee is valid for attribution only, but the router emits no
+  `OriginFeeApplied` event for it. Its deposits are attributable only from the transaction calldata and SDK
+  telemetry.
+- **Process-global.** `attribution` is process-global: the last `AugustSDK` constructed wins, and one
+  constructed without `attribution` clears it. Run one attribution configuration per process.
+
 ## Architecture
 
 ```

package/lib/adapters/evm/index.d.ts

@@ -1,4 +1,4 @@
-import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult, type IClaimWithdrawalOptions } from '../../modules/vaults/write.actions';
+import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult, type IClaimWithdrawalOptions, type IGetDepositRouteOptions } from '../../modules/vaults/write.actions';
 import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions, ISwapRouterDepositOptions, ISwapRouterDepositResultOptions } from '../../types';
 import { type IPreviewDepositOptions, type IPreviewRedeemOptions, type IAllowanceOptions, type IBalanceOfOptions, type IMaxDepositOptions, type IGetIdleLiquidityOptions, type ILagDurationOptions, type IGetWithdrawalEpochOptions, type IWithdrawalEpoch, type IGetBurnableAmountByReceiverOptions, type IGetRequirementByDateOptions, type IGetScheduledTransactionsByDateOptions, type IScheduledTransactionsByDate } from '../../modules/vaults/read.actions';
 import { type CompatibleSigner } from '../../core/helpers/signer';
@@ -74,7 +74,9 @@ declare class EVMAdapter {
     /**
      * Deposit into an August vault. Routes automatically: V1 single-asset vaults
      * deposit the underlying directly; V2 multi-asset vaults route through the
-     * adapter for non-underlying `depositAsset`. If allowance is insufficient
+     * adapter for non-underlying `depositAsset`. With `attribution.originCode`
+     * configured, eligible deposits go through the SwapRouter instead (see
+     * {@link EVMAdapter.getDepositRoute}). If allowance is insufficient
      * the method submits an approve transaction first (the approve step always
      * waits for confirmation to close a race window, regardless of `wait`).
      *
@@ -98,6 +100,22 @@ declare class EVMAdapter {
      * ```
      */
     vaultDeposit(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Resolve whether a deposit goes through the SwapRouter with the instance
+     * origin code or takes the vault's native path, and the address to approve
+     * (`route.spender`, not necessarily the vault). See {@link getDepositRoute}.
+     *
+     * @param options - {@link IGetDepositRouteOptions}.
+     * @returns `{ via, spender, reason? }` — `reason` explains a native route.
+     * @throws AugustValidationError on an invalid target, or an unregistered
+     *   code under `attribution.strictOrigin`.
+     * @throws AugustSDKError when a backend, vault or router read fails.
+     * @example
+     * ```ts
+     * const { via, spender } = await augustSdk.evm.getDepositRoute({ target: vault });
+     * ```
+     */
+    getDepositRoute(options: IGetDepositRouteOptions): Promise<import("../../modules/vaults/write.actions").IDepositRoute>;
     /**
      * Submit a redemption request against a vault. Shares are escrowed and the
      * underlying assets are released asynchronously by the protocol; callers
@@ -194,9 +212,9 @@ declare class EVMAdapter {
     /**
      * Deposit into a vault through the on-chain `SwapRouter`, choosing the router
      * path from `depositAsset` (direct deposit, native wrap, or a swap to the
-     * reference asset). The high-level, explicit counterpart to the SwapRouter
-     * branch inside {@link vaultDeposit} — the caller opts into the router
-     * deliberately, so a native-deposit vault is never accidentally swapped.
+     * reference asset). The explicit, opt-in swap entry point —
+     * {@link vaultDeposit} never swaps — so a native-deposit vault is never
+     * accidentally swapped.
      *
      * Reads the vault's reference asset + decimals on-chain, resolves the swap
      * quote and fail-closes on aggregator/whitelist drift, and sends the ERC-20

package/lib/adapters/evm/index.js

@@ -119,7 +119,9 @@ class EVMAdapter {
     /**
      * Deposit into an August vault. Routes automatically: V1 single-asset vaults
      * deposit the underlying directly; V2 multi-asset vaults route through the
-     * adapter for non-underlying `depositAsset`. If allowance is insufficient
+     * adapter for non-underlying `depositAsset`. With `attribution.originCode`
+     * configured, eligible deposits go through the SwapRouter instead (see
+     * {@link EVMAdapter.getDepositRoute}). If allowance is insufficient
      * the method submits an approve transaction first (the approve step always
      * waits for confirmation to close a race window, regardless of `wait`).
      *
@@ -146,6 +148,25 @@ class EVMAdapter {
         const signer = await this._getSigner();
         return (0, write_actions_1.vaultDeposit)(signer, options);
     }
+    /**
+     * Resolve whether a deposit goes through the SwapRouter with the instance
+     * origin code or takes the vault's native path, and the address to approve
+     * (`route.spender`, not necessarily the vault). See {@link getDepositRoute}.
+     *
+     * @param options - {@link IGetDepositRouteOptions}.
+     * @returns `{ via, spender, reason? }` — `reason` explains a native route.
+     * @throws AugustValidationError on an invalid target, or an unregistered
+     *   code under `attribution.strictOrigin`.
+     * @throws AugustSDKError when a backend, vault or router read fails.
+     * @example
+     * ```ts
+     * const { via, spender } = await augustSdk.evm.getDepositRoute({ target: vault });
+     * ```
+     */
+    async getDepositRoute(options) {
+        const signer = await this._getSigner();
+        return (0, write_actions_1.getDepositRoute)(signer, options);
+    }
     /**
      * Submit a redemption request against a vault. Shares are escrowed and the
      * underlying assets are released asynchronously by the protocol; callers
@@ -257,9 +278,9 @@ class EVMAdapter {
     /**
      * Deposit into a vault through the on-chain `SwapRouter`, choosing the router
      * path from `depositAsset` (direct deposit, native wrap, or a swap to the
-     * reference asset). The high-level, explicit counterpart to the SwapRouter
-     * branch inside {@link vaultDeposit} — the caller opts into the router
-     * deliberately, so a native-deposit vault is never accidentally swapped.
+     * reference asset). The explicit, opt-in swap entry point —
+     * {@link vaultDeposit} never swaps — so a native-deposit vault is never
+     * accidentally swapped.
      *
      * Reads the vault's reference asset + decimals on-chain, resolves the swap
      * quote and fail-closes on aggregator/whitelist drift, and sends the ERC-20

package/lib/core/analytics/method-taxonomy.js

@@ -52,6 +52,8 @@ exports.METHOD_CATEGORIES = {
     getSwapRouterDepositResult: 'read.vault',
     getSwapRouterWhitelistedTokens: 'read.vault',
     getSwapRouterEligibleVaults: 'read.vault',
+    getOriginInfo: 'read.vault',
+    getDepositRoute: 'read.vault',
     getVaultPositions: 'read.position',
     getVaultUserHistory: 'read.position',
     getUserHistory: 'read.position',

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.8.0";
+export declare const SDK_VERSION = "9.9.1";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.8.0';
+exports.SDK_VERSION = '9.9.1';
 //# sourceMappingURL=version.js.map

package/lib/core/attribution.d.ts

@@ -20,7 +20,7 @@
  */
 export declare const ERC8021_MARKER = "80218021802180218021802180218021";
 /**
- * Configuration for ERC-8021 calldata-suffix attribution (Base Builder Codes).
+ * ERC-8021 builder-code attribution and the SwapRouter origin code — independent; set either or both.
  *
  * @example
  * ```typescript
@@ -36,9 +36,10 @@ export interface IAttributionConfig {
     /**
      * Builder codes to embed in the suffix, e.g. from base.dev registration
      * (`bc_…`). ASCII strings of 1–64 characters each; the comma-joined list
-     * must fit in 255 bytes (schema 0 length prefix is a single byte).
+     * must fit in 255 bytes (schema 0 length prefix is a single byte). Omit to
+     * send no ERC-8021 suffix.
      */
-    builderCodes: string[];
+    builderCodes?: string[];
     /**
      * EVM chain IDs to attribute. Omit to attribute writes on every EVM chain
      * (the suffix is inert on chains without an ERC-8021 indexer and costs
@@ -53,6 +54,22 @@ export interface IAttributionConfig {
      * receives the suffix anyway cannot be transacted on from a Ledger at all.
      */
     chains?: number[];
+    /**
+     * SwapRouter origin (referral / fee-sharing) code: the `bytes32` registered
+     * via the router's `addOrigin`, as `0x` + 64 hex chars. Every Ethereum
+     * mainnet SwapRouter deposit carries it unless the call passes its own
+     * `originCode`; it is never sent on another chain. Omit to send the
+     * all-zero sentinel (no origin fee). Unaffected by `chains`. An
+     * unregistered code reverts with `InvalidOrigin` — check it with
+     * `getOriginInfo` first.
+     */
+    originCode?: `0x${string}`;
+    /**
+     * When `true`, a deposit route that would use the SwapRouter with an
+     * `originCode` not registered there throws `AugustValidationError` before
+     * any transaction, instead of falling back to the vault's native path.
+     */
+    strictOrigin?: boolean;
 }
 /**
  * Build an ERC-8021 schema-0 attribution suffix from builder codes.
@@ -78,16 +95,31 @@ export declare function buildAttributionSuffix(codes: string[]): string;
  *
  * Called unconditionally on every `AugustSDK` construction — an instance
  * that omits `attribution` passes `null` and RESETS the state, so a prior
- * instance's builder codes never leak into a later instance in the same
- * process (same semantics as `setPublicApiBaseUrl`).
+ * instance's builder codes or origin code never leak into a later instance
+ * in the same process (same semantics as `setPublicApiBaseUrl`).
  *
  * @param config Attribution config from the SDK constructor, or `null` to
  *   disable attribution.
  * @throws Error when the config's builder codes fail validation — thrown
  *   synchronously from the constructor so misconfiguration is caught at
  *   init, not on the first write.
+ * @throws {@link AugustValidationError} when `originCode` is not a 32-byte
+ *   hex string.
  */
 export declare function setAttribution(config: IAttributionConfig | null): void;
+/**
+ * Whether {@link IAttributionConfig.strictOrigin} is set on the SDK instance.
+ *
+ * @returns `true` when an unregistered origin code must fail a deposit.
+ */
+export declare function isStrictOrigin(): boolean;
+/**
+ * The SwapRouter origin code configured on the SDK instance via
+ * {@link IAttributionConfig.originCode}.
+ *
+ * @returns The `bytes32` code, or `null` when none is configured.
+ */
+export declare function getOriginCode(): `0x${string}` | null;
 /**
  * Whether attribution is configured at all, independent of any chain gate.
  *

package/lib/core/attribution.js

@@ -18,9 +18,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERC8021_MARKER = void 0;
 exports.buildAttributionSuffix = buildAttributionSuffix;
 exports.setAttribution = setAttribution;
+exports.isStrictOrigin = isStrictOrigin;
+exports.getOriginCode = getOriginCode;
 exports.isAttributionEnabled = isAttributionEnabled;
 exports.getAttributionSuffix = getAttributionSuffix;
 exports.appendAttributionSuffix = appendAttributionSuffix;
+const swap_router_1 = require("./constants/swap-router");
+const errors_1 = require("./errors");
 /**
  * The 16-byte ERC-8021 suffix terminator. The last 16 bytes of an attributed
  * transaction's calldata are always this marker; parsers read backwards from
@@ -71,31 +75,63 @@ function buildAttributionSuffix(codes) {
 }
 let activeSuffix = null;
 let activeChains = null;
+let activeOriginCode = null;
+let activeStrictOrigin = false;
 /**
  * Set (or clear) the process-global attribution config.
  *
  * Called unconditionally on every `AugustSDK` construction — an instance
  * that omits `attribution` passes `null` and RESETS the state, so a prior
- * instance's builder codes never leak into a later instance in the same
- * process (same semantics as `setPublicApiBaseUrl`).
+ * instance's builder codes or origin code never leak into a later instance
+ * in the same process (same semantics as `setPublicApiBaseUrl`).
  *
  * @param config Attribution config from the SDK constructor, or `null` to
  *   disable attribution.
  * @throws Error when the config's builder codes fail validation — thrown
  *   synchronously from the constructor so misconfiguration is caught at
  *   init, not on the first write.
+ * @throws {@link AugustValidationError} when `originCode` is not a 32-byte
+ *   hex string.
  */
 function setAttribution(config) {
     if (!config) {
         activeSuffix = null;
         activeChains = null;
+        activeOriginCode = null;
+        activeStrictOrigin = false;
         return;
     }
-    activeSuffix = buildAttributionSuffix(config.builderCodes);
+    const { originCode } = config;
+    if (originCode !== undefined && !swap_router_1.ORIGIN_CODE_PATTERN.test(originCode)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: attribution.originCode must be a 32-byte hex string (0x + 64 hex chars), got ${String(originCode).length} chars. Pass the bytes32 code registered on the SwapRouter via addOrigin.`, { context: { expectedLength: 66 } });
+    }
+    activeSuffix =
+        config.builderCodes === undefined
+            ? null
+            : buildAttributionSuffix(config.builderCodes);
     activeChains =
         Array.isArray(config.chains) && config.chains.length > 0
             ? config.chains
             : null;
+    activeOriginCode = originCode ?? null;
+    activeStrictOrigin = config.strictOrigin === true;
+}
+/**
+ * Whether {@link IAttributionConfig.strictOrigin} is set on the SDK instance.
+ *
+ * @returns `true` when an unregistered origin code must fail a deposit.
+ */
+function isStrictOrigin() {
+    return activeStrictOrigin;
+}
+/**
+ * The SwapRouter origin code configured on the SDK instance via
+ * {@link IAttributionConfig.originCode}.
+ *
+ * @returns The `bytes32` code, or `null` when none is configured.
+ */
+function getOriginCode() {
+    return activeOriginCode;
 }
 /**
  * Whether attribution is configured at all, independent of any chain gate.

package/lib/core/base.class.d.ts

@@ -120,12 +120,18 @@ export interface IAugustBase {
      * offchain indexers (base.dev) can credit the transaction to your app.
      * Omit to send unattributed transactions (the default).
      *
+     * `attribution.originCode` sets the SwapRouter origin (referral /
+     * fee-sharing) code that every Ethereum mainnet SwapRouter deposit made
+     * through the SDK carries unless the call passes its own.
+     *
      * Note: this is a process-global override applied on EVERY construction —
      * the last `AugustSDK` instantiated is authoritative, and one that omits
      * `attribution` RESETS it (same semantics as `publicApiBaseUrl`).
      *
      * @throws Throws synchronously from the constructor when the builder codes
      *   are malformed — see {@link IAttributionConfig}.
+     * @throws AugustValidationError synchronously from the constructor when
+     *   `originCode` is not a 32-byte hex string.
      */
     attribution?: IAttributionConfig;
 }

package/lib/core/constants/core.d.ts

@@ -117,6 +117,7 @@ export declare const WEBSERVER_ENDPOINTS: {
             summary: (vaultAddress: IAddress) => string;
             withdrawals: (chain: string, vaultAddress: IAddress) => string;
             debank: (vaultAddress: IAddress) => string;
+            octav: (vaultAddress: IAddress) => string;
             userHistory: (vaultAddress: IAddress, wallet: IAddress) => string;
             archivedVaults: string;
         };

package/lib/core/constants/core.js

@@ -184,6 +184,7 @@ exports.WEBSERVER_ENDPOINTS = {
             summary: (vaultAddress) => `/tokenized_vault/vault_summary/${(0, ethers_1.getAddress)(vaultAddress)}`,
             withdrawals: (chain, vaultAddress) => `/withdrawals/${chain}/${(0, ethers_1.getAddress)(vaultAddress)}`,
             debank: (vaultAddress) => `/tokenized_vault/${(0, ethers_1.getAddress)(vaultAddress)}/debank`,
+            octav: (vaultAddress) => `/tokenized_vault/${subaccountSegment(vaultAddress)}/octav`,
             // Mongo-backed deposit/withdraw history for archived vaults whose
             // subgraph has been (or will be) retired. See fetchArchivedVaults.
             userHistory: (vaultAddress, wallet) => `/upshift/vault_history/${(0, ethers_1.getAddress)(vaultAddress)}?wallet=${(0, ethers_1.getAddress)(wallet)}`,

package/lib/core/constants/swap-router.d.ts

@@ -31,10 +31,11 @@ export declare const SWAP_ROUTER_NAMES: Readonly<Record<number, string>>;
  *    deposit surface for a vault; and
  *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
  *
- * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` is the
- * native/multiasset/adapter path and never routes through the SwapRouter. That
- * separation is what stops a natively-accepted asset from being silently
- * swapped — the regression that implicit auto-routing caused. Any-token swap
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` never
+ * swaps, and uses the SwapRouter only for a direct deposit carrying a
+ * configured origin code (see `getDepositRoute`). That separation is what
+ * stops a natively-accepted asset from being silently swapped — the
+ * regression that implicit auto-routing caused. Any-token swap
  * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
  *
  * Membership requires the vault to be registered on-chain
@@ -93,6 +94,22 @@ export declare const ORIGIN_CODES: {
     /** All-zero sentinel — no origin fee. */
     readonly default: `0x${string}`;
 };
+/**
+ * Shape of a SwapRouter origin code: `0x` followed by exactly 64 hex chars
+ * (a `bytes32`). Shared by every origin-code entry point so the constructor
+ * option, the per-call override and the registration read validate the same
+ * way.
+ * @internal
+ */
+export declare const ORIGIN_CODE_PATTERN: RegExp;
+/**
+ * Chains on which the SDK sends the instance origin code
+ * (`attribution.originCode`). Ethereum mainnet only: it is the one SwapRouter
+ * deployment whose origin registry has been verified. On any other chain the
+ * instance code is never sent, even where a SwapRouter is configured; an
+ * `originCode` passed to a call is still sent.
+ */
+export declare const ORIGIN_ATTRIBUTION_CHAINS: readonly number[];
 /**
  * Maximum number of swap legs the contract accepts in a single
  * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading

package/lib/core/constants/swap-router.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.SWAP_ROUTER_DEPLOY_BLOCKS = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_NAMES = exports.SWAP_ROUTER_ADDRESSES = void 0;
+exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_ATTRIBUTION_CHAINS = exports.ORIGIN_CODE_PATTERN = exports.ORIGIN_CODES = exports.SWAP_ROUTER_DEPLOY_BLOCKS = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_NAMES = exports.SWAP_ROUTER_ADDRESSES = void 0;
 /**
  * Address of the `SwapRouter` periphery contract on each supported chain.
  *
@@ -39,10 +39,11 @@ exports.SWAP_ROUTER_NAMES = {
  *    deposit surface for a vault; and
  *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
  *
- * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` is the
- * native/multiasset/adapter path and never routes through the SwapRouter. That
- * separation is what stops a natively-accepted asset from being silently
- * swapped — the regression that implicit auto-routing caused. Any-token swap
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` never
+ * swaps, and uses the SwapRouter only for a direct deposit carrying a
+ * configured origin code (see `getDepositRoute`). That separation is what
+ * stops a natively-accepted asset from being silently swapped — the
+ * regression that implicit auto-routing caused. Any-token swap
  * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
  *
  * Membership requires the vault to be registered on-chain
@@ -109,6 +110,22 @@ exports.ORIGIN_CODES = {
     /** All-zero sentinel — no origin fee. */
     default: '0x0000000000000000000000000000000000000000000000000000000000000000',
 };
+/**
+ * Shape of a SwapRouter origin code: `0x` followed by exactly 64 hex chars
+ * (a `bytes32`). Shared by every origin-code entry point so the constructor
+ * option, the per-call override and the registration read validate the same
+ * way.
+ * @internal
+ */
+exports.ORIGIN_CODE_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Chains on which the SDK sends the instance origin code
+ * (`attribution.originCode`). Ethereum mainnet only: it is the one SwapRouter
+ * deployment whose origin registry has been verified. On any other chain the
+ * instance code is never sent, even where a SwapRouter is configured; an
+ * `originCode` passed to a call is still sent.
+ */
+exports.ORIGIN_ATTRIBUTION_CHAINS = [1];
 /**
  * Maximum number of swap legs the contract accepts in a single
  * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading

package/lib/core/helpers/swap-router.d.ts

@@ -1,5 +1,5 @@
 import { type Signer, type Wallet } from 'ethers';
-import type { IAddress, ISwapRouterDepositResult, ISwapRouterDepositResultOptions } from '../../types';
+import type { IAddress, IContractRunner, IGetOriginInfoOptions, IOriginInfo, ISwapRouterDepositResult, ISwapRouterDepositResultOptions } from '../../types';
 /**
  * Resolve the `SwapRouter` address for a chain.
  *
@@ -39,7 +39,7 @@ export declare function getSwapRouterName(chainId: number): string | undefined;
  *
  * This gates the (flag-controlled) swap-router deposit UI and can fail-fast a
  * {@link swapRouterDeposit} call. It does **not** affect {@link vaultDeposit},
- * which is always the native/multiasset/adapter path.
+ * which never swaps (see `getDepositRoute` for when it uses the router).
  *
  * @param vaultAddress - August vault address.
  * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
@@ -62,18 +62,24 @@ export declare const vaultUsesSwapRouter: typeof isSwapRouterEligible;
 /**
  * Normalize an optional origin code to the value to send on-chain.
  *
- * Returns the caller-supplied code when present, otherwise the default
- * (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
+ * Returns the caller-supplied code when present (an explicit all-zero
+ * sentinel opts one call out), otherwise the SDK instance's
+ * `attribution.originCode` when `chainId` is in
+ * {@link ORIGIN_ATTRIBUTION_CHAINS} (Ethereum mainnet only), otherwise the
+ * default (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
  * supplied code is exactly 32 bytes (66 chars including the `0x` prefix);
  * the on-chain SwapRouter reverts with `InvalidOrigin` otherwise, but
  * surfacing the failure here as a typed SDK error gives partners a
  * grepable Sentry event instead of a generic `execution reverted`.
  *
  * @param provided - Optional caller-supplied origin code.
+ * @param chainId - Chain the deposit is sent on. The instance code is never
+ *   returned without it, or on a chain outside
+ *   {@link ORIGIN_ATTRIBUTION_CHAINS}.
  * @returns The 32-byte origin code to pass to the router.
  * @throws {@link AugustValidationError} when `provided` is not a 32-byte hex string.
  */
-export declare function resolveOriginCode(provided?: `0x${string}`): `0x${string}`;
+export declare function resolveOriginCode(provided?: `0x${string}`, chainId?: number): `0x${string}`;
 /**
  * Resolves the real, post-execution outcome of a SwapRouter deposit from its
  * mined transaction receipt. The SwapRouter contract itself emits no
@@ -108,6 +114,61 @@ export declare function resolveOriginCode(provided?: `0x${string}`): `0x${string
  * ```
  */
 export declare function getSwapRouterDepositResult(signer: Signer | Wallet, { txHash, vault }: ISwapRouterDepositResultOptions): Promise<ISwapRouterDepositResult | null>;
+/**
+ * Read how an origin code is registered on a chain's `SwapRouter`: whether it
+ * exists, its origin fee, and its fee collector.
+ *
+ * Check a partner code with this before configuring it as
+ * `attribution.originCode` — the router reverts every deposit carrying an
+ * unregistered code with `InvalidOrigin`. A code is registered when its
+ * collector is non-zero (`addOrigin` always sets one); a zero-fee code is
+ * still registered but never emits `OriginFeeApplied`. Cached per (chain,
+ * router, code) for 5 minutes.
+ *
+ * @param options - {@link IGetOriginInfoOptions}.
+ * @returns {@link IOriginInfo}; `registered: false` with a zero fee and
+ *   collector, and no RPC, on a chain with no SwapRouter deployment.
+ * @throws {@link AugustValidationError} when `originCode` is not a 32-byte hex
+ *   string.
+ * @throws {@link AugustSDKError} when the `origins(bytes32)` read fails.
+ * @worstCaseRpcCalls 1 — one `origins(bytes32)` call; none on a cache hit.
+ * @example
+ * ```ts
+ * const info = await getOriginInfo({ chainId: 1, originCode, rpcUrl });
+ * if (!info.registered) throw new Error('origin code is not registered');
+ * ```
+ */
+export declare function getOriginInfo({ chainId, originCode, rpcUrl, }: IGetOriginInfoOptions): Promise<IOriginInfo>;
+/**
+ * {@link getOriginInfo} without input validation, reading through a caller
+ * runner (created lazily, only on a cache miss). Shared with the deposit-route
+ * resolver so both hit the same cache entry.
+ * @internal
+ */
+export declare function readOriginInfo(chainId: number, originCode: `0x${string}`, runner: () => IContractRunner): Promise<IOriginInfo>;
+/**
+ * Read a vault's `SwapRouter` registration (`vaultInfo`), cached for 5
+ * minutes like the other router reads.
+ *
+ * @returns The router's `referenceAsset` for the vault (the zero address when
+ *   it is not registered) and its `vaultType`; `undefined` on a chain with no
+ *   SwapRouter.
+ * @internal
+ */
+export declare function readSwapRouterVaultInfo(runner: IContractRunner, chainId: number, vault: IAddress): Promise<{
+    referenceAsset: IAddress;
+    vaultType: number;
+} | undefined>;
+/**
+ * Read whether a chain's `SwapRouter` whitelists `token`
+ * (`whitelistedTokens`), cached for 5 minutes like the other router reads.
+ * `SwapRouter.deposit` reverts `InputTokenNotWhitelisted` for any token it
+ * does not whitelist, the vault's reference asset included.
+ *
+ * @returns `false` on a chain with no SwapRouter.
+ * @internal
+ */
+export declare function readSwapRouterTokenWhitelisted(runner: IContractRunner, chainId: number, token: IAddress): Promise<boolean>;
 /**
  * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
  * chain — the any-token set a UI can offer as swap-and-deposit inputs.