@arca-network/sdk 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/arca.js CHANGED
@@ -186,18 +186,28 @@ function isIdFormat(value) {
186
186
  }
187
187
  /**
188
188
  * Pre-computed function selectors (first 4 bytes of keccak256 of the signature)
189
- * for the ArcaCustodyPool contract. These are fixed since the contract ABI is known.
189
+ * for the v4 ArcaCustodyKernel contract. These are fixed since the contract ABI
190
+ * is known, and are pinned by a keccak-derived selector test.
190
191
  *
191
- * Verified against: `cast sig "lockBoundary(bytes32)"` etc. from Foundry.
192
+ * Verified against: `cast sig "claimRecovery(bytes32)"` etc. from Foundry.
193
+ *
194
+ * NOTE: the pre-reset v1 pool ABI (`withdraw`, `assignRecoveryKey`,
195
+ * `setTimeLock`, `cancelPendingExit`, `recoveryWithdrawAccount`) no longer
196
+ * exists on-chain — those builders were removed. The v4 sovereign-exit path is
197
+ * `claimRecovery` → wait `RECOVERY_WINDOW` (7 days) → `recoveryWithdraw`, with
198
+ * `cancelRecovery` to abort a false-alarm claim and `setCosignKey` to delegate
199
+ * or rotate the day-to-day co-sign key. `lockBoundary` / `unlockBoundary` are
200
+ * the operator/coordinator operational freeze (kept for coordinator tooling;
201
+ * they are NOT the sovereign recovery path — the kernel gates them on the
202
+ * boundary coordinator, not the recovery key).
192
203
  */
193
204
  const CUSTODY_SELECTORS = {
194
205
  'lockBoundary(bytes32)': '0x67f82a1d',
195
206
  'unlockBoundary(bytes32)': '0x83a2f7cd',
196
- 'withdraw(bytes32)': '0x8e19899e',
197
- 'assignRecoveryKey(bytes32,address)': '0xf5b7e3a6',
198
- 'setTimeLock(bytes32,uint256)': '0x3e41d187',
199
- 'cancelPendingExit(bytes32)': '0x5e50fbe8',
200
- 'recoveryWithdrawAccount(bytes32)': '0xba7b2fbd',
207
+ 'claimRecovery(bytes32)': '0x9180c0a6',
208
+ 'cancelRecovery(bytes32)': '0x631fec7f',
209
+ 'recoveryWithdraw(bytes32)': '0x28bcced4',
210
+ 'setCosignKey(bytes32,address)': '0xbc919ffc',
201
211
  };
202
212
  /**
203
213
  * Minimal ABI encoder for custody contract calls.
@@ -289,6 +299,18 @@ function mergeOrderWithPosition(newSide, newSize, fillPrice, existing) {
289
299
  }
290
300
  return { size: newSize - exSize, entry: fillPrice, side: newSide };
291
301
  }
302
+ /**
303
+ * Format a size to at most `decimals` fractional digits, stripping trailing
304
+ * zeros, for use as a canonical decimal string (e.g. `0.0001`, `3.34`, `10`).
305
+ */
306
+ function formatSizeToDecimals(n, decimals) {
307
+ if (decimals <= 0)
308
+ return String(Math.round(n));
309
+ const fixed = n.toFixed(decimals);
310
+ // Strip trailing zeros (and a dangling decimal point) — the leading "\.?"
311
+ // only matches when the trailing zeros consume the entire fractional part.
312
+ return fixed.replace(/\.?0+$/, '') || '0';
313
+ }
292
314
  class Arca {
293
315
  static fees = {
294
316
  // The Arca network takes no transfer fee. Only applications (builder /
@@ -738,6 +760,18 @@ class Arca {
738
760
  * are transferred to that Arca before deletion.
739
761
  *
740
762
  * If the object is already deleted, returns the existing state.
763
+ *
764
+ * Authorization is value-aware: deleting an object that holds no value
765
+ * (zero settled balance, no venue equity, no open positions) never
766
+ * requires browser step-up — on any realm type, including with API keys.
767
+ * Deleting a funded object on a production realm requires step-up, and
768
+ * if the object's isolation boundary is co-sign armed the request is
769
+ * refused with `412 COSIGN_DRAIN_REQUIRED` (an {@link ArcaError} with
770
+ * that code): drain the object via a co-signed withdrawal first, then
771
+ * delete the then-empty object. Treat `COSIGN_DRAIN_REQUIRED` as
772
+ * blocked-pending-user, not retryable. Use
773
+ * `GET /objects/{id}/deletion-readiness` (`authorization` field) to
774
+ * determine the path without probing.
741
775
  */
742
776
  ensureDeleted(opts) {
743
777
  return this.op(() => this.client.post('/objects/delete', {
@@ -1535,11 +1569,68 @@ class Arca {
1535
1569
  }
1536
1570
  /**
1537
1571
  * Get exchange account state (equity, margin, positions, orders).
1572
+ *
1573
+ * On a real Hyperliquid venue, immediately after {@link ensurePerpsExchange}
1574
+ * resolves the underlying account's agent wallet may still be registering.
1575
+ * In that window this throws {@link ExchangeProvisioningError} (503
1576
+ * `EXCHANGE_PROVISIONING`) — a transient, self-healing state. Use
1577
+ * {@link waitForExchangeReady} to poll until the account is tradeable
1578
+ * rather than treating the first 503 as a failure.
1538
1579
  */
1539
1580
  async getExchangeState(objectId) {
1540
1581
  await this.ready();
1541
1582
  return this.client.get(`/objects/${objectId}/exchange/state`);
1542
1583
  }
1584
+ /**
1585
+ * Block until a perps exchange arca's underlying venue account has finished
1586
+ * provisioning and is ready to trade, then return its {@link ExchangeState}.
1587
+ *
1588
+ * Why this exists: {@link ensurePerpsExchange} resolves when the exchange
1589
+ * arca object is `active`, but on a **real** Hyperliquid venue the account's
1590
+ * agent wallet is registered and stamped asynchronously (minutes on
1591
+ * HyperEVM). Reads and orders issued in that window fail with
1592
+ * {@link ExchangeProvisioningError} (503 `EXCHANGE_PROVISIONING`). On the
1593
+ * **simulated** venue provisioning is instantaneous, so the first poll
1594
+ * succeeds and this returns immediately — parity for both venues.
1595
+ *
1596
+ * The poll treats only `EXCHANGE_PROVISIONING` as "keep waiting". Any other
1597
+ * error (a genuine venue fault, a not-found object, an auth failure) is
1598
+ * re-thrown immediately — this helper never masks a real failure as a
1599
+ * timeout. If the account is still provisioning when `timeoutMs` elapses,
1600
+ * the last {@link ExchangeProvisioningError} is re-thrown so callers can
1601
+ * still branch on it by type.
1602
+ *
1603
+ * @param objectId - Exchange Arca object ID.
1604
+ * @param opts.timeoutMs - Max time to wait. Default 300000 (5 min) to cover
1605
+ * real HyperEVM agent-registration latency.
1606
+ * @param opts.pollIntervalMs - Delay between polls. Default 3000.
1607
+ */
1608
+ async waitForExchangeReady(objectId, opts = {}) {
1609
+ const timeoutMs = opts.timeoutMs ?? 300000;
1610
+ const pollIntervalMs = opts.pollIntervalMs ?? 3000;
1611
+ const deadline = Date.now() + timeoutMs;
1612
+ let lastProvisioning;
1613
+ for (;;) {
1614
+ try {
1615
+ return await this.getExchangeState(objectId);
1616
+ }
1617
+ catch (err) {
1618
+ if (!(err instanceof errors_1.ExchangeProvisioningError)) {
1619
+ // Genuine fault (venue error, not-found, auth) — never swallow it.
1620
+ throw err;
1621
+ }
1622
+ lastProvisioning = err;
1623
+ }
1624
+ if (Date.now() + pollIntervalMs >= deadline) {
1625
+ // Out of budget while still provisioning: surface the transient error
1626
+ // (not a generic timeout) so callers keep the EXCHANGE_PROVISIONING
1627
+ // signal and can decide to keep waiting.
1628
+ throw lastProvisioning ??
1629
+ new errors_1.ExchangeProvisioningError(`Exchange account ${objectId} was still provisioning after ${timeoutMs}ms`);
1630
+ }
1631
+ await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
1632
+ }
1633
+ }
1543
1634
  /**
1544
1635
  * Get active asset trading data for an exchange object: max trade sizes,
1545
1636
  * available margin, mark price, and fee rate. Accounts for leverage,
@@ -1919,17 +2010,32 @@ class Arca {
1919
2010
  return result;
1920
2011
  }
1921
2012
  /**
1922
- * Open a position and attach reduce-only TP/SL triggers in **one atomic
1923
- * batch** — Hyperliquid `normalTpsl` parity. The entry and its triggers are
1924
- * submitted as a single signed batch to one operation: the whole bracket
1925
- * validates and commits at the venue, or none of it does. The trigger legs
1926
- * **arm only when the entry fills**, and the venue links them with a shared
1927
- * one-cancels-the-other group so a fill on one cancels its sibling.
2013
+ * Open a position and attach reduce-only TP/SL triggers as a **linked
2014
+ * `normalTpsl` bracket** — Hyperliquid parity. The entry and its triggers are
2015
+ * submitted as a single signed batch to one operation; one signature links
2016
+ * the legs. The trigger legs **arm only when the entry fills**, and the venue
2017
+ * links them with a shared one-cancels-the-other group so a fill on one
2018
+ * cancels its sibling.
2019
+ *
2020
+ * **`normalTpsl` is a fixed-size parent-order bracket.** Each TP/SL child
2021
+ * defaults to the entry's size (a normalTpsl child is a fixed-size leg of the
2022
+ * parent order, NOT a whole-position trigger). Pass `takeProfitSz` /
2023
+ * `stopLossSz` for a smaller partial-close child. For a **whole-position**
2024
+ * TP/SL that sizes to the entire live position (Hyperliquid `positionTpsl`),
2025
+ * use {@link setStopLoss} / {@link setTakeProfit} / {@link setPositionTpsl}
2026
+ * instead — that is a separate trigger-only model with no entry leg and is
2027
+ * not accepted here.
1928
2028
  *
1929
2029
  * Returns one {@link OrderHandle} per leg (`entry`, `takeProfit?`,
1930
2030
  * `stopLoss?`), all backed by the single bracket operation. At least one of
1931
- * `takeProfitPx` / `stopLossPx` is required. The TP/SL legs are unsized
1932
- * (`sizeToMax`) reduce-only triggers that close the entire position.
2031
+ * `takeProfitPx` / `stopLossPx` is required. Until the entry fills, a TP/SL
2032
+ * child is not yet a live venue order (it has no venue order id — it is
2033
+ * addressable only by its cloid); its {@link OrderHandle} matches fills by
2034
+ * cloid, and cancelling it before activation cancels the parent bracket.
2035
+ *
2036
+ * A single signature links the legs, but this is **not** a globally
2037
+ * all-or-none batch: Hyperliquid only guarantees whole-payload rejection for
2038
+ * pre-validation failures.
1933
2039
  *
1934
2040
  * @example
1935
2041
  * ```ts
@@ -1960,17 +2066,17 @@ class Arca {
1960
2066
  const closingSide = opts.side === 'buy' ? 'sell' : 'buy';
1961
2067
  const tif = opts.timeInForce ?? 'GTC';
1962
2068
  // Build orders[] in request order: entry first, then the trigger legs.
2069
+ // A `normalTpsl` child is a FIXED-SIZE leg of the parent order: it defaults
2070
+ // to the entry's size. An explicit `sz` is a smaller partial-close child.
2071
+ // We never send `sizeToMax` here — that is the whole-position `positionTpsl`
2072
+ // model, which this endpoint rejects (use setStopLoss / setTakeProfit).
1963
2073
  const trigger = (tpsl, triggerPx, sz) => {
1964
- const sized = sz != null && sz !== '';
2074
+ const childSize = sz != null && sz !== '' ? sz : opts.size;
1965
2075
  return {
1966
2076
  market: opts.market,
1967
2077
  side: closingSide,
1968
2078
  orderType: triggersAreMarket ? 'MARKET' : 'LIMIT',
1969
- // Sized: a partial reduce-only close of exactly `sz` (reduce-only caps
1970
- // it at the live position). Unsized: carries no quantity and closes the
1971
- // whole live position when it fires (size is ignored by the venue).
1972
- size: sized ? sz : '0',
1973
- ...(sized ? {} : { sizeToMax: true }),
2079
+ size: childSize,
1974
2080
  reduceOnly: true,
1975
2081
  isTrigger: true,
1976
2082
  triggerPx,
@@ -2299,13 +2405,106 @@ class Arca {
2299
2405
  getOrderLimits() {
2300
2406
  return { minOrderNotionalUsd: 10 };
2301
2407
  }
2408
+ /**
2409
+ * Compute the minimum valid order size for a market at a given price.
2410
+ *
2411
+ * The venue enforces a minimum order **notional** (`size * price`), but a UI
2412
+ * that takes a size in base-asset units needs that expressed as a minimum
2413
+ * **size**. This converts the market's `minOrderNotionalUsd` into a size,
2414
+ * rounded **up** to the market's `szDecimals` precision so the result always
2415
+ * clears the floor. Reduce-only orders and unsized (`sizeToMax: true`)
2416
+ * trigger orders are exempt (they can be any positive size down to one tick)
2417
+ * so dust positions can always be closed.
2418
+ *
2419
+ * Pass either a {@link Market} or a canonical id; when given an id the market
2420
+ * metadata is fetched (and cached) via {@link Arca.market}. When the market
2421
+ * has no `minOrderNotionalUsd` (older server), the venue-wide
2422
+ * {@link Arca.getOrderLimits} default is used.
2423
+ *
2424
+ * @example
2425
+ * ```ts
2426
+ * const { minSize, minNotionalUsd } = await arca.getMinOrderSize({
2427
+ * market: "hl:0:BTC",
2428
+ * price: markPrice,
2429
+ * });
2430
+ * // Disable the submit button when the input is below `minSize`, and show
2431
+ * // "Minimum order is {minSize} BTC (${minNotionalUsd})".
2432
+ * ```
2433
+ */
2434
+ async getMinOrderSize(opts) {
2435
+ const market = typeof opts.market === 'string' ? await this.market(opts.market) : opts.market;
2436
+ const szDecimals = market?.szDecimals ?? 5;
2437
+ const minNotional = market?.minOrderNotionalUsd ?? this.getOrderLimits().minOrderNotionalUsd;
2438
+ const factor = 10 ** szDecimals;
2439
+ const tick = 1 / factor;
2440
+ // Reduce-only and unsized trigger orders are exempt from the notional
2441
+ // minimum — any positive size down to one tick is allowed.
2442
+ if (opts.reduceOnly || (opts.isTrigger && opts.sizeToMax)) {
2443
+ return { minSize: formatSizeToDecimals(tick, szDecimals), minNotionalUsd: 0 };
2444
+ }
2445
+ const price = typeof opts.price === 'string' ? Number.parseFloat(opts.price) : opts.price;
2446
+ if (!Number.isFinite(price) || price <= 0) {
2447
+ // Can't convert notional → size without a valid price; return one tick so
2448
+ // the caller at least enforces the precision floor.
2449
+ return { minSize: formatSizeToDecimals(tick, szDecimals), minNotionalUsd: minNotional };
2450
+ }
2451
+ // Round up to szDecimals precision. Subtract a tiny epsilon on the scaled
2452
+ // value so floating-point noise on an exact boundary (e.g. 10 / 100000)
2453
+ // doesn't overshoot by a full tick.
2454
+ let minSizeNum = Math.ceil(minNotional / price * factor - 1e-6) / factor;
2455
+ if (minSizeNum < tick)
2456
+ minSizeNum = tick;
2457
+ return { minSize: formatSizeToDecimals(minSizeNum, szDecimals), minNotionalUsd: minNotional };
2458
+ }
2459
+ /**
2460
+ * Validate an order size against the market's minimum before calling
2461
+ * {@link Arca.placeOrder}. Advisory only — the server (sim-exchange and
2462
+ * Hyperliquid) remains the authoritative enforcement point; use this to gate
2463
+ * a UI and show a consistent message.
2464
+ *
2465
+ * @example
2466
+ * ```ts
2467
+ * const check = await arca.validateOrderSize({ market: "hl:0:BTC", price, size });
2468
+ * if (!check.ok) showError(check.reason); // else enable submit
2469
+ * ```
2470
+ */
2471
+ async validateOrderSize(opts) {
2472
+ const { minSize, minNotionalUsd } = await this.getMinOrderSize(opts);
2473
+ const size = typeof opts.size === 'string' ? Number.parseFloat(opts.size) : opts.size;
2474
+ if (!Number.isFinite(size) || size <= 0) {
2475
+ return { ok: false, reason: 'Order size must be a positive number.', minSize, minNotionalUsd };
2476
+ }
2477
+ // Exempt orders (reduce-only / unsized trigger) only need a positive size.
2478
+ const exempt = Boolean(opts.reduceOnly || (opts.isTrigger && opts.sizeToMax));
2479
+ if (exempt) {
2480
+ return { ok: true, minSize, minNotionalUsd };
2481
+ }
2482
+ if (size < Number.parseFloat(minSize)) {
2483
+ const price = typeof opts.price === 'string' ? Number.parseFloat(opts.price) : opts.price;
2484
+ const notional = Number.isFinite(price) ? size * price : 0;
2485
+ return {
2486
+ ok: false,
2487
+ reason: `Order notional $${notional.toFixed(2)} is below venue minimum of $${minNotionalUsd}. ` +
2488
+ `Minimum size is ${minSize}.`,
2489
+ minSize,
2490
+ minNotionalUsd,
2491
+ };
2492
+ }
2493
+ return { ok: true, minSize, minNotionalUsd };
2494
+ }
2302
2495
  /**
2303
2496
  * List positions for an exchange Arca object.
2304
2497
  */
2305
2498
  async listPositions(objectId) {
2306
2499
  await this.ready();
2307
2500
  const response = await this.client.get(`/objects/${objectId}/exchange/positions`);
2308
- return response.positions;
2501
+ // The exchange/positions endpoint returns `positions: null` (not `[]`) when
2502
+ // the account has no open positions — the normal state after a full drain.
2503
+ // Returning it raw crashed every `.find()` caller (`closePosition`,
2504
+ // `resolvePositionSide`, and the real-money benchmark's drain step) with
2505
+ // "Cannot read properties of null (reading 'find')" (the 2026-07-12 finding).
2506
+ // Normalize to an empty array so "no positions" is always an empty list.
2507
+ return response.positions ?? [];
2309
2508
  }
2310
2509
  /**
2311
2510
  * Close an open position (fully or partially) with `reduceOnly` enforced.
@@ -2793,6 +2992,44 @@ class Arca {
2793
2992
  this.historyCache.set(key, result);
2794
2993
  return result;
2795
2994
  }
2995
+ /**
2996
+ * Get market-wide SETTLED funding-rate history for a market.
2997
+ *
2998
+ * Returns the venue's real settlement series — each observation carries the
2999
+ * settlement time (`t`, Unix ms), the settled `fundingRate`, and the
3000
+ * `premium` — in chronological order. This is distinct from the
3001
+ * account-scoped funding *payments* streamed by {@link Arca.watchFunding};
3002
+ * these are the market-wide rates that drive those payments.
3003
+ *
3004
+ * `market` must be a canonical market id (e.g. `"hl:0:BTC"`, `"hl:1:TSLA"`);
3005
+ * HIP-3 markets are supported where history exists. Funding is an event
3006
+ * series, so there is no `interval`. The default window is the trailing 7
3007
+ * days; the documented maximum window is 30 days. Returns an empty array for
3008
+ * an unknown market or a range with no data.
3009
+ *
3010
+ * These are settled historical rates, never predicted — for the
3011
+ * current/predicted rate read the ticker's `funding` + `nextFundingTime`.
3012
+ */
3013
+ async getFundingHistory(market, options) {
3014
+ const key = (0, cache_1.buildCacheKey)('fundingHistory', {
3015
+ market,
3016
+ startTime: options?.startTime !== undefined ? String(options.startTime) : undefined,
3017
+ endTime: options?.endTime !== undefined ? String(options.endTime) : undefined,
3018
+ });
3019
+ const cached = this.historyCache.get(key);
3020
+ if (cached)
3021
+ return cached;
3022
+ await this.ready();
3023
+ const params = {};
3024
+ if (options?.startTime !== undefined)
3025
+ params.startTime = String(options.startTime);
3026
+ if (options?.endTime !== undefined)
3027
+ params.endTime = String(options.endTime);
3028
+ const result = await this.client.get(`/exchange/market/funding/${market}`, params);
3029
+ if (result.funding.length > 0)
3030
+ this.historyCache.set(key, result);
3031
+ return result;
3032
+ }
2796
3033
  /**
2797
3034
  * Get sparkline close-price arrays for all tracked coins in a single request.
2798
3035
  * Returns a map of market name to an array of 24 hourly close prices.
@@ -3492,89 +3729,112 @@ class Arca {
3492
3729
  });
3493
3730
  }
3494
3731
  /**
3495
- * Prepare an unsigned `lockBoundary` transaction.
3496
- * The caller signs and submits this transaction from their recovery key wallet.
3497
- * Locking freezes all operator fund movement and cancels any pending exit.
3498
- */
3499
- prepareLockBoundary(contractAddress, chainId, boundaryId) {
3500
- return {
3501
- to: contractAddress,
3502
- data: encodeCustodyCall('lockBoundary(bytes32)', [boundaryId]),
3503
- chainId,
3504
- value: '0',
3505
- };
3506
- }
3507
- /**
3508
- * Prepare an unsigned `unlockBoundary` transaction.
3509
- * Only the actor who locked the boundary can unlock it.
3732
+ * Prepare an unsigned `claimRecovery` transaction — the v4 sovereign
3733
+ * escape hatch. The recovery key holder signs and broadcasts this from their
3734
+ * own wallet; no operator involvement.
3735
+ *
3736
+ * `claimRecovery` arms the recovery channel on the boundary: it stamps the
3737
+ * recovery-claim timestamp (starting the fixed 7-day `RECOVERY_WINDOW`
3738
+ * clock), freezes value-out, and triggers venue agent revocation. It is the
3739
+ * ONLY action that arms recovery — distinct from the operator's
3740
+ * `lockBoundary` operational freeze, which never starts a recovery window.
3741
+ * Requires: caller is the boundary's recovery key.
3742
+ *
3743
+ * After the window elapses, call `prepareRecoveryWithdraw` to sweep the
3744
+ * balance. To abort a false alarm before withdrawing, use
3745
+ * `prepareCancelRecovery`.
3510
3746
  */
3511
- prepareUnlockBoundary(contractAddress, chainId, boundaryId) {
3747
+ prepareClaimRecovery(contractAddress, chainId, boundaryId) {
3512
3748
  return {
3513
3749
  to: contractAddress,
3514
- data: encodeCustodyCall('unlockBoundary(bytes32)', [boundaryId]),
3750
+ data: encodeCustodyCall('claimRecovery(bytes32)', [boundaryId]),
3515
3751
  chainId,
3516
3752
  value: '0',
3517
3753
  };
3518
3754
  }
3519
3755
  /**
3520
- * Prepare an unsigned `withdraw` transaction.
3521
- * Withdraws the entire boundary balance to the recovery key holder.
3522
- * Requires: boundary is locked by the caller, caller is recovery key holder.
3756
+ * Prepare an unsigned `cancelRecovery` transaction. Closes an in-flight
3757
+ * recovery claim (false alarm), clearing the window clock and re-enabling
3758
+ * normal value flows. Requires: caller is the boundary's recovery key and a
3759
+ * claim is currently in progress.
3760
+ *
3761
+ * Note the kernel does NOT re-arm the venue agents `claimRecovery` revoked;
3762
+ * re-establishing trading authority after a cancel is a separate step.
3523
3763
  */
3524
- prepareWithdraw(contractAddress, chainId, boundaryId) {
3764
+ prepareCancelRecovery(contractAddress, chainId, boundaryId) {
3525
3765
  return {
3526
3766
  to: contractAddress,
3527
- data: encodeCustodyCall('withdraw(bytes32)', [boundaryId]),
3767
+ data: encodeCustodyCall('cancelRecovery(bytes32)', [boundaryId]),
3528
3768
  chainId,
3529
3769
  value: '0',
3530
3770
  };
3531
3771
  }
3532
3772
  /**
3533
- * Prepare an unsigned `assignRecoveryKey` transaction for changing an existing key.
3534
- * When the boundary already has a recovery key, only the current holder can change it.
3535
- * For initial assignment (no existing key), use `registerRecoveryKey()` instead.
3773
+ * Prepare an unsigned `recoveryWithdraw` transaction. Sweeps the entire
3774
+ * boundary balance to the recovery key holder. Requires: caller is the
3775
+ * boundary's recovery key, an active recovery claim exists, and the 7-day
3776
+ * `RECOVERY_WINDOW` has elapsed (or the operator fast-tracked it).
3777
+ *
3778
+ * This replaces the pre-reset v1 `withdraw(bytes32)` builder.
3536
3779
  */
3537
- prepareAssignRecoveryKey(contractAddress, chainId, boundaryId, newRecoveryKey) {
3780
+ prepareRecoveryWithdraw(contractAddress, chainId, boundaryId) {
3538
3781
  return {
3539
3782
  to: contractAddress,
3540
- data: encodeCustodyCall('assignRecoveryKey(bytes32,address)', [boundaryId, newRecoveryKey]),
3783
+ data: encodeCustodyCall('recoveryWithdraw(bytes32)', [boundaryId]),
3541
3784
  chainId,
3542
3785
  value: '0',
3543
3786
  };
3544
3787
  }
3545
3788
  /**
3546
- * Prepare an unsigned `setTimeLock` transaction.
3547
- * Recovery key holders can only increase the time lock; never decrease.
3789
+ * Prepare an unsigned `setCosignKey` transaction. Delegates or rotates the
3790
+ * boundary's day-to-day co-sign key — the key that authorizes routine
3791
+ * operator-driven withdrawals via a per-action EIP-712 signature. The
3792
+ * co-sign key is a delegation FROM the sovereign recovery key.
3793
+ *
3794
+ * Access: INITIAL delegation (no co-sign key yet) is recovery-key-only;
3795
+ * ROTATION is by the current co-sign key OR the recovery key. The
3796
+ * operator/coordinator can never seat a co-sign key. `newCosignKey` may be a
3797
+ * bare EOA (the fast path) or an `IArcaCosignVerifier` contract (the shared
3798
+ * `CosignRegistry`, for multi-device / passkey co-sign).
3799
+ *
3800
+ * This replaces the pre-reset v1 `assignRecoveryKey(bytes32,address)`
3801
+ * builder; the recovery key itself is still assigned via `registerRecoveryKey`
3802
+ * (operator-assisted) or rotated via the 2-of-2 `rotate-recovery-key` flow.
3548
3803
  */
3549
- prepareSetTimeLock(contractAddress, chainId, boundaryId, durationSeconds) {
3804
+ prepareSetCosignKey(contractAddress, chainId, boundaryId, newCosignKey) {
3550
3805
  return {
3551
3806
  to: contractAddress,
3552
- data: encodeCustodyCall('setTimeLock(bytes32,uint256)', [boundaryId, durationSeconds.toString()]),
3807
+ data: encodeCustodyCall('setCosignKey(bytes32,address)', [boundaryId, newCosignKey]),
3553
3808
  chainId,
3554
3809
  value: '0',
3555
3810
  };
3556
3811
  }
3557
3812
  /**
3558
- * Prepare an unsigned `cancelPendingExit` transaction.
3559
- * Can be called by recovery key holder or operator.
3813
+ * Prepare an unsigned `lockBoundary` transaction — the operator/coordinator
3814
+ * OPERATIONAL freeze (incident response). This is NOT the sovereign recovery
3815
+ * path: the kernel gates `lockBoundary` on the boundary's coordinator, so it
3816
+ * cannot be broadcast from a self-custody recovery-key wallet — it is exposed
3817
+ * here only for coordinator-side tooling that builds calldata. For the
3818
+ * sovereign freeze-and-exit, use `prepareClaimRecovery`.
3560
3819
  */
3561
- prepareCancelPendingExit(contractAddress, chainId, boundaryId) {
3820
+ prepareLockBoundary(contractAddress, chainId, boundaryId) {
3562
3821
  return {
3563
3822
  to: contractAddress,
3564
- data: encodeCustodyCall('cancelPendingExit(bytes32)', [boundaryId]),
3823
+ data: encodeCustodyCall('lockBoundary(bytes32)', [boundaryId]),
3565
3824
  chainId,
3566
3825
  value: '0',
3567
3826
  };
3568
3827
  }
3569
3828
  /**
3570
- * Prepare an unsigned `recoveryWithdrawAccount` transaction.
3571
- * Sweeps an exchange arca's balance back to its boundary.
3572
- * Requires: boundary is locked by the recovery key holder.
3829
+ * Prepare an unsigned `unlockBoundary` transaction — reverses the operator's
3830
+ * operational `lockBoundary`. Callable only by the address that placed the
3831
+ * lock (the coordinator). Like `prepareLockBoundary`, this is coordinator
3832
+ * tooling, not the sovereign recovery path.
3573
3833
  */
3574
- prepareRecoveryWithdrawAccount(contractAddress, chainId, arcaId) {
3834
+ prepareUnlockBoundary(contractAddress, chainId, boundaryId) {
3575
3835
  return {
3576
3836
  to: contractAddress,
3577
- data: encodeCustodyCall('recoveryWithdrawAccount(bytes32)', [arcaId]),
3837
+ data: encodeCustodyCall('unlockBoundary(bytes32)', [boundaryId]),
3578
3838
  chainId,
3579
3839
  value: '0',
3580
3840
  };