@0xmonaco/contracts 1.0.47 → 1.0.50

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type Hex, predictSweeperAddress, type SweeperAddressInput, sweeperCloneInitCode, sweeperImmutableArgs } from "./sweeper";
+export { type DepositTarget, encodeDepositApplicationData, type Hex, predictSweeperAddress, type SweeperAddressInput, sweeperCloneInitCode, sweeperImmutableArgs, } from "./sweeper";
 /**
  * Contract ABIs for all protocol contracts.
  * These ABIs are used to interact with the deployed contracts.

package/dist/index.js

@@ -6,7 +6,7 @@
  * for all Monaco protocol contracts.
  */
 import { SWEEPER_ABI, SWEEPER_FACTORY_ABI, VAULT_ABI } from "./abis";
-export { predictSweeperAddress, sweeperCloneInitCode, sweeperImmutableArgs } from "./sweeper";
+export { encodeDepositApplicationData, predictSweeperAddress, sweeperCloneInitCode, sweeperImmutableArgs, } from "./sweeper";
 /**
  * Contract ABIs for all protocol contracts.
  * These ABIs are used to interact with the deployed contracts.

package/dist/sweeper.d.ts

@@ -2,17 +2,56 @@
  * Off-chain derivation of Monaco sweeper deposit addresses.
  *
  * A sweeper is an EIP-1167 clone deployed by `SweeperFactory` at a CREATE2
- * address determined by the (clientId, user) pair it is bound to. The address
- * can therefore be shown to a user — and funded — before any contract exists
- * there, without an RPC round trip.
+ * address determined by the (clientId, user, deposit target) triple it is
+ * bound to. The address can therefore be shown to a user — and funded — before
+ * any contract exists there, without an RPC round trip.
  *
  * The client id is the application's identifier as used for rollup deposits
  * (the string `sdk.login` takes). It is hashed **byte-for-byte**: two
  * spellings derive two different, both-valid addresses, so the exact string
  * of the registered application must be used — the backend rejects unknown
  * spellings at registration because the lookup is an exact match.
+ *
+ * The deposit target is hashed the same way, through the encoding in
+ * {@link encodeDepositApplicationData}, so `"spot"` and `"margin"` are two
+ * different addresses for one application and user, each carrying its own
+ * target. A `"spot"` address is never credited to margin.
+ *
+ * The reverse is not absolute: `"margin"` is a routing *request*. A deposit the
+ * backend cannot route to collateral — an unsupported collateral asset, or a
+ * margin account that fails validation — is credited to the spot wallet
+ * instead, so funds are never stranded. Derivation fixes which request the
+ * address carries, not which ledger the credit ultimately lands in.
  */
 export type Hex = `0x${string}`;
+/**
+ * Which ledger a deposit asks to be credited to.
+ *
+ * `"spot"` credits the spot wallet; `"margin"` asks for the parent margin
+ * account's collateral. The target is part of the sweeper address derivation,
+ * so the same pair has one deposit address per target.
+ *
+ * `"margin"` is a request: a deposit the backend cannot route to collateral
+ * falls back to the spot wallet rather than being stranded.
+ */
+export type DepositTarget = "spot" | "margin";
+/**
+ * Encodes the on-chain `applicationData` a deposit carries.
+ *
+ * Spot is the identity encoding — the bare client id, byte for byte. Not a
+ * shortcut but a compatibility requirement: the deposit address is a hash of
+ * this string, so encoding spot any other way would move every address already
+ * published to a user.
+ *
+ * Margin emits the canonical routing payload the backend decodes. It is built
+ * with `JSON.stringify` rather than string concatenation so a client id
+ * containing a quote, a backslash, or a brace is escaped instead of breaking
+ * out of the object. Key order is fixed and part of the derivation.
+ *
+ * The byte-for-byte counterpart of `encode_application_data` in
+ * `utils/src/deposit_routing.rs`.
+ */
+export declare function encodeDepositApplicationData(clientId: string, target: DepositTarget): string;
 export interface SweeperAddressInput {
     /** Address of the deployed `SweeperFactory`. */
     factory: string;
@@ -25,14 +64,25 @@ export interface SweeperAddressInput {
     clientId: string;
     /** Address credited on the rollup when the sweeper sweeps. */
     user: string;
+    /**
+     * Which ledger swept deposits ask to be credited to. Defaults to `"spot"`,
+     * which reproduces the derivation from before deposit targets existed.
+     *
+     * Must match the `depositTarget` the pair was registered with: the target is
+     * inside the derivation, so a mismatch derives a real, fundable address that
+     * nothing is monitoring. Anything but `"spot"` or `"margin"` throws rather
+     * than defaulting, for the same reason.
+     */
+    depositTarget?: DepositTarget;
 }
 /**
- * Derives the deposit address for a (clientId, user) pair.
+ * Derives the deposit address for a (clientId, user, deposit target) triple.
  *
  * @returns The EIP-55 checksummed sweeper address, deployed or not.
- * @throws If any address is malformed or the client id is empty.
+ * @throws If any address is malformed, the client id is empty, or the deposit
+ *   target is not exactly `"spot"` or `"margin"`.
  */
-export declare function predictSweeperAddress({ factory, implementation, clientId, user }: SweeperAddressInput): Hex;
+export declare function predictSweeperAddress({ factory, implementation, clientId, user, depositTarget }: SweeperAddressInput): Hex;
 /**
  * The clone's immutable args: `abi.encode(address user, string clientId)`
  * (the contract calls the string `applicationId`, matching the rollup's

package/dist/sweeper.js

@@ -14,17 +14,56 @@ const CLONE_RUNTIME_LENGTH = 45;
  */
 const SALT = new Uint8Array(32);
 /**
- * Derives the deposit address for a (clientId, user) pair.
+ * Encodes the on-chain `applicationData` a deposit carries.
+ *
+ * Spot is the identity encoding — the bare client id, byte for byte. Not a
+ * shortcut but a compatibility requirement: the deposit address is a hash of
+ * this string, so encoding spot any other way would move every address already
+ * published to a user.
+ *
+ * Margin emits the canonical routing payload the backend decodes. It is built
+ * with `JSON.stringify` rather than string concatenation so a client id
+ * containing a quote, a backslash, or a brace is escaped instead of breaking
+ * out of the object. Key order is fixed and part of the derivation.
+ *
+ * The byte-for-byte counterpart of `encode_application_data` in
+ * `utils/src/deposit_routing.rs`.
+ */
+export function encodeDepositApplicationData(clientId, target) {
+    assertDepositTarget(target);
+    return target === "margin" ? JSON.stringify({ clientId, depositTarget: "MARGIN" }) : clientId;
+}
+/**
+ * Rejects anything that is not exactly `"spot"` or `"margin"`.
+ *
+ * Without this, `target === "margin" ? … : …` sends every other value down the
+ * spot branch, so an untyped JavaScript caller — or one who passed the wire
+ * form `"MARGIN"` copied from the API reference — silently derives a real,
+ * fundable **spot** address while believing it is a margin one. That is the
+ * same failure the backend refuses with a 400 rather than defaulting, and it is
+ * worse here: nothing round-trips through a server to reveal the mistake.
+ */
+function assertDepositTarget(value) {
+    if (value !== "spot" && value !== "margin") {
+        throw new Error(`Invalid deposit target: ${JSON.stringify(value)}. ` + 'Expected "spot" or "margin" — lowercase, not the wire form "SPOT"/"MARGIN".');
+    }
+}
+/**
+ * Derives the deposit address for a (clientId, user, deposit target) triple.
  *
  * @returns The EIP-55 checksummed sweeper address, deployed or not.
- * @throws If any address is malformed or the client id is empty.
+ * @throws If any address is malformed, the client id is empty, or the deposit
+ *   target is not exactly `"spot"` or `"margin"`.
  */
-export function predictSweeperAddress({ factory, implementation, clientId, user }) {
+export function predictSweeperAddress({ factory, implementation, clientId, user, depositTarget = "spot" }) {
     const factoryAddress = assertAddress(factory, "factory");
     const implementationAddress = assertAddress(implementation, "implementation");
     const userAddress = assertNonZeroUser(assertAddress(user, "user"));
     assertClientId(clientId);
-    const initCode = sweeperCloneInitCode(implementationAddress, sweeperImmutableArgs(userAddress, clientId));
+    // The bound string is the encoded application data, not the bare client id:
+    // it is what the clone carries and what a sweep puts on-chain.
+    const boundClientId = encodeDepositApplicationData(clientId, depositTarget);
+    const initCode = sweeperCloneInitCode(implementationAddress, sweeperImmutableArgs(userAddress, boundClientId));
     const preimage = concatBytes(Uint8Array.of(0xff), hexToBytes(factoryAddress), SALT, keccak_256(hexToBytes(initCode)));
     return toChecksumAddress(`0x${bytesToHex(keccak_256(preimage).slice(12))}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/contracts",
-	"version": "1.0.47",
+	"version": "1.0.50",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",