@ninsei-labs/sdk 0.39.3 → 0.40.0-develop.1

package/engine/evm/gasReserve.js

@@ -1,55 +1,74 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/gasReserve.js for the SDK package.
-// Edit the source under www/js, then run: node tools/build-sdk-engine.mjs
-// tools/check-sdk-engine.mjs reddens on any drift, so a stale copy cannot ship silently.
+// Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
 // Everything below this header is identical to the source.
 
-// ЗАПАС ГАЗА ПОКУПАТЕЛЯ НА ДЕЙСТВИЯ ОРДЕРА (issue #97, часть B): ОТМЕТКА ГОТОВНОСТИ И ВОЗМОЖНЫЙ ВОЗВРАТ.
+// THE BUYER GAS RESERVE FOR ORDER ACTIONS: THE READINESS MARK AND A POSSIBLE REFUND.
 //
-// СУТЬ. В прямом обмене человек вносит средства в эскроу, а после прихода XMR сам зовёт markReady (когда XMR
-// подтверждены) либо refund (когда сделка не состоялась). Оба вызова стоят газа в НАТИВНОЙ монете сети, и у
-// человека, пришедшего из USDC, своего натива нет. Поэтому ДО котировки решается, СКОЛЬКО НАТИВА ОСТАВИТЬ под
-// эти два вызова; решение показывается и в ETH, и в долларах, а строкой входит в разбивку цены.
+// THE POINT. In a direct swap the person deposits into the escrow, and after the XMR arrives calls markReady itself
+// (when the XMR is confirmed) or refund (when the swap did not happen). Both calls cost gas in the network
+// NATIVE coin, and a person coming from USDC has no native of their own. So BEFORE the quote it is decided HOW MUCH
+// NATIVE to leave for those two calls; the decision is shown both in ETH and in dollars, and enters the price breakdown as a line.
 //
-// ПОЧЕМУ ЧИСТЫЕ ФУНКЦИИ. Решение стоит денег и обязано проверяться без сети (tools/check-buy-gas-reserve.mjs)
-// и считаться ОДНИМ И ТЕМ ЖЕ кодом на экране и в прогоне. Сеть касается только чтения цены газа - его
-// подставляет вызывающий (www/js/evm/prices.js кладёт gasPriceWei в живые цены, экран передаёт его сюда).
+// WHY PURE FUNCTIONS. The decision costs money and must be checked without a network
+// and computed by THE SAME code on screen and in the run. Only reading the gas price touches the network - the
+// caller supplies it (www/js/evm/prices.js puts gasPriceWei into the live prices, the screen passes it here).
 //
-// ЧИСЛА НЕ ВЫДУМАНЫ. Пределы газа - те же, с которыми НАШ ЖЕ код отправляет обе транзакции
-// (движок сделки теперь в пакете: sdk/src/swap-flow.mjs - markReadyOrder - gas 120000, refundOrder - gas 250000). Проверка
-// tools/check-buy-gas-reserve.mjs сверяет обе константы со строками того файла, поэтому правка одного места
-// без другого краснит прогон - ровно так же, как это сделано для газа забора в rfq/reverseGas.mjs.
+// THE NUMBERS ARE NOT INVENTED. The gas limits are the same ones OUR OWN code sends both transactions with
+// (the swap engine is now in the package: sdk/src/swap-flow.mjs - markReadyOrder - gas 120000, refundOrder - gas
+// 250000). The check compares both constants against the lines of that file, so
+// editing one place without the other reddens the run - exactly as done for the claim gas in rfq/reverseGas.mjs.
 //
-// ПОЧЕМУ ЗАПАС ФИКСИРУЕТСЯ ДО КОТИРОВКИ. `amount` ордера входит в ПОДПИСАННУЮ котировку, и решение о запасе
-// меняет итоговую сумму взноса; значит оно принимается ДО запроса котировки и дальше не пересчитывается.
-// Экран кладёт готовый план в состояние формы (www/js/ui/views/swapForm.js), а экран подписи пользуется тем
-// же зафиксированным планом - второй пересчёт разошёлся бы с первым.
+// WHY THE RESERVE IS FIXED BEFORE THE QUOTE. The order `amount` is part of the SIGNED quote, and the reserve
+// decision changes the final deposit amount; so it is made BEFORE the quote request and not recomputed afterwards.
+// The screen puts the ready plan into the form state (www/js/ui/views/swapForm.js), and the signing screen uses the
+// same fixed plan - a second recomputation would diverge from the first.
 
-// ПРЕДЕЛЫ ГАЗА - ИЗ НАШЕГО ЖЕ КОДА. Строки-источники: sdk/src/swap-flow.mjs (gas: 120_000n у отметки и
-// gas: 250_000n у возврата). Заниженный предел - это отказ уже после раскрытия половины; неиспользованный
-// газ в лимите не списывается, поэтому запас берётся с запасом.
+// THE DEPOSIT'S GAS COMES FROM THE FUNDING CODE, NOT FROM A SECOND NUMBER. `orderGasReservePlan` below can
+// include the escrow deposit (createOrderAndFund, evm/funding.js: GAS_CREATE_ORDER_AND_FUND): on the path where
+// the wallet holds no native of its own the deposit is paid AFTER the swap, so its gas must be part of the
+// reserve that decides whether the wallet can afford the path. The constant is imported, not copied.
+import { GAS_CREATE_ORDER_AND_FUND } from "./funding.js";
+
+// THE GAS LIMITS ARE FROM OUR OWN CODE. Source lines: sdk/src/swap-flow.mjs (gas: 120_000n at the mark and
+// gas: 250_000n at the refund). A limit set too low is a refusal already after the half is revealed; unused
+// gas in the limit is not charged, so the reserve is taken with a margin.
 export const ORDER_READY_GAS_LIMIT = 120_000n;   // markReady - sdk/src/swap-flow.mjs markReadyOrder
 export const ORDER_REFUND_GAS_LIMIT = 250_000n;  // refund   - sdk/src/swap-flow.mjs refundOrder
 export const ORDER_GAS_LIMIT = ORDER_READY_GAS_LIMIT + ORDER_REFUND_GAS_LIMIT;
+// THE ESCROW DEPOSIT'S OWN GAS LIMIT - the same number funding sends createOrderAndFund with. It is NOT folded
+// into ORDER_GAS_LIMIT (that constant's meaning - the mark and the refund - stays intact for the checks that pin
+// it); it is added ON TOP when the path pays the deposit separately (the no-own-native path), see
+// orderGasReserveWei's `depositGasLimit`.
+export const ORDER_DEPOSIT_GAS_LIMIT = GAS_CREATE_ORDER_AND_FUND;
 
 const toBig = (v) => {
   if (v === null || v === undefined || v === "") return null;
   try { return BigInt(typeof v === "bigint" ? v : String(v)); } catch { return null; }
 };
 
-// СКОЛЬКО ВЕЙ НУЖНО НА ОБА ВЫЗОВА. Цену газа даёт цепь, пределы - наши. Ноль цены и нечитаемое число
-// означают «не измерено», и это НЕ ноль газа: неизвестное требование обязано называться, а не выдаваться за
-// ноль (то же правило, что у газа забора: rfq/reverseGas.mjs).
-export function orderGasReserveWei({ gasPriceWei, readyGasLimit = ORDER_READY_GAS_LIMIT, refundGasLimit = ORDER_REFUND_GAS_LIMIT } = {}) {
+// HOW MANY WEI IS NEEDED FOR BOTH CALLS. The gas price comes from the chain, the limits are ours. A zero price
+// and an unreadable number mean "not measured", and this is NOT zero gas: an unknown requirement must be named,
+// not passed off as zero (the same rule as for the claim gas: rfq/reverseGas.mjs).
+export function orderGasReserveWei({ gasPriceWei, readyGasLimit = ORDER_READY_GAS_LIMIT, refundGasLimit = ORDER_REFUND_GAS_LIMIT, depositGasLimit = 0n, extraFeeWei = 0n } = {}) {
   const gp = toBig(gasPriceWei);
   if (gp === null || gp <= 0n) return null;
   const ready = toBig(readyGasLimit);
   const refund = toBig(refundGasLimit);
-  if (ready === null || refund === null || ready <= 0n || refund <= 0n) return null;
-  return gp * (ready + refund);
+  // THE DEPOSIT IS OPT-IN AND DEFAULTS TO ZERO: the mark+refund reserve is unchanged for every existing caller
+  // (and the checks that pin 370 000 gas). A no-own-native path passes ORDER_DEPOSIT_GAS_LIMIT here so the reserve
+  // it is judged against includes the deposit it will pay after the swap. A negative deposit is a defect -> null.
+  const deposit = toBig(depositGasLimit);
+  // THE SECOND LEG'S EXTRA FEE (a composed route) IS ADDED ON TOP, and it is a FLAT wei amount, not gas: the
+  // conversion WETH->native costs the person that fee, so the native the path must cover is larger by it. Defaults to
+  // zero so every existing caller (and the checks pinning the mark+refund reserve) is unchanged.
+  const extra = toBig(extraFeeWei);
+  if (ready === null || refund === null || deposit === null || extra === null) return null;
+  if (ready <= 0n || refund <= 0n || deposit < 0n || extra < 0n) return null;
+  return gp * (ready + refund + deposit) + extra;
 }
 
-// ПОКАЗ В ОБЕИХ ВЕЛИЧИНАХ. У человека, пришедшего из USDC, нет чувства масштаба ETH, поэтому запас показан и
-// в ETH, и в долларах. Доллар - оценка по живому курсу натива; нет курса - нет и оценки (null), а не выдумка.
+// DISPLAY IN BOTH UNITS. A person coming from USDC has no sense of ETH scale, so the reserve is shown both
+// in ETH and in dollars. The dollar is an estimate at the live native rate; no rate - no estimate (null), not a made-up one.
 export function gasReserveDisplay({ reserveWei, nativeUsd, decimals = 18 } = {}) {
   const w = toBig(reserveWei);
   if (w === null || w <= 0n) return null;
@@ -58,9 +77,9 @@ export function gasReserveDisplay({ reserveWei, nativeUsd, decimals = 18 } = {})
   return { native, usd };
 }
 
-// РЕШЕНИЕ ПО ГАЛОЧКЕ. Галочка НУЖНА, только когда своего натива НЕ ХВАТАЕТ на оба вызова; при достатке ETH
-// она не показывается вовсе - человек платит своим газом, и просить у него нечего. Нечитаемый баланс натива -
-// отдельное состояние: запас предлагаем (лучше предложить, чем промолчать о нехватке), и это названо полем.
+// DECISION BY THE CHECKBOX. The checkbox is NEEDED only when one own native is NOT ENOUGH for both calls; with enough
+// ETH it is not shown at all - the person pays with their own gas, and there is nothing to ask of them. An unreadable
+// native balance is a separate state: we offer the reserve (better to offer than stay silent about the shortfall), and this is named by a field.
 export function gasReserveChoice({ nativeBalanceWei, reserveWei } = {}) {
   const need = toBig(reserveWei);
   if (need === null || need <= 0n) return { measured: false, enough: null, show: false, balanceUnread: false };
@@ -69,16 +88,28 @@ export function gasReserveChoice({ nativeBalanceWei, reserveWei } = {}) {
   return { measured: true, enough: have >= need, show: have < need, balanceUnread: false };
 }
 
-// ПОЛНОЕ РЕШЕНИЕ ОДНИМ ОБЪЕКТОМ - именно оно фиксируется в состоянии формы до котировки. Все числовые поля -
-// строки либо null: так план переживает запись и чтение, и BigInt не превращается в «[object BigInt]».
-export function orderGasReservePlan({ gasPriceWei = null, nativeBalanceWei = null, nativeUsd = null, decimals = 18 } = {}) {
-  const reserveWei = orderGasReserveWei({ gasPriceWei });
+// THE WHOLE DECISION IN ONE OBJECT - exactly what is fixed in the form state before the quote. All numeric fields
+// are strings or null: so the plan survives writing and reading, and BigInt does not become "[object BigInt]".
+export function orderGasReservePlan({ gasPriceWei = null, nativeBalanceWei = null, nativeUsd = null, decimals = 18, depositGasLimit = 0n, extraFeeWei = 0n } = {}) {
+  // depositGasLimit is carried INTO the reserve (see orderGasReserveWei): on the no-own-native path the plan must
+  // be honest about the deposit the wallet will pay after the swap, so the reserve it decides on is larger. On a
+  // COMPOSED route extraFeeWei additionally carries the second leg's own fee, which is deducted from the swap
+  // proceeds - so the reserve must cover it too.
+  const reserveWei = orderGasReserveWei({ gasPriceWei, depositGasLimit, extraFeeWei });
+  const deposit = toBig(depositGasLimit);
+  const extra = toBig(extraFeeWei);
   const display = reserveWei === null ? null : gasReserveDisplay({ reserveWei, nativeUsd, decimals });
   const choice = gasReserveChoice({ nativeBalanceWei, reserveWei });
   return {
     measured: reserveWei !== null,
     gasPriceWei: gasPriceWei === null || gasPriceWei === undefined ? null : String(gasPriceWei),
     reserveWei: reserveWei === null ? null : reserveWei.toString(),
+    // THE DEPOSIT IS REPORTED SEPARATELY as well: a reader must be able to see how much of the reserve is the
+    // escrow deposit rather than the mark/refund, and a drift between this field and the constant reddens a check.
+    depositGasLimit: deposit === null ? null : deposit.toString(),
+    // THE SECOND LEG'S FEE IS REPORTED SEPARATELY as well, so a reader sees how much of the reserve is the
+    // conversion fee rather than gas or the deposit, and a drift between this field and the number reddens a check.
+    extraFeeWei: extra === null ? null : extra.toString(),
     native: display ? display.native : null,
     usd: display ? display.usd : null,
     enough: choice.enough,

package/engine/evm/index.js

@@ -1,19 +1,12 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/index.js for the SDK package.
-// Edit the source under www/js, then run: node tools/build-sdk-engine.mjs
-// tools/check-sdk-engine.mjs reddens on any drift, so a stale copy cannot ship silently.
+// Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
 // Everything below this header is identical to the source.
 
-// Кошелёк, которым пользуется интерфейс демки.
-//
-// Реализация одна: WalletConnect (www/js/evm/walletconnect.js) - настоящий кошелёк
-// пользователя, настоящие балансы. Раньше здесь был выбор режима (WalletConnect или
-// встроенный демо-кошелёк) для Demo controls; демо-кошелёк убран вместе с переключателем,
-// потому что мы движемся к настоящему продукту, а не к макету.
-//
-// Чего в демке по-прежнему НЕТ: переводов. Контракта escrow ещё не существует, адрес escrow
-// генерируется моком (www/js/mock/chain.js), поэтому шаг фондирования остаётся имитацией -
-// simulateEscrowFunding() ниже. Когда контракт появится, на его месте будет
-// provider.sendTransaction/eth_sendTransaction, а имитация исчезнет вместе с моком цепочки.
+// The wallet used by the demo interface.
+// One implementation: WalletConnect (www/js/evm/walletconnect.js) - the user's real wallet, real balances.
+// The built-in demo wallet and its mode switch were removed: we are heading to a real product, not a mockup.
+// Still NO transfers: there is no escrow contract yet and the address is mocked (mock/chain.js), so funding
+// is a simulation (simulateEscrowFunding below); provider.sendTransaction will replace it.
 
 import {
   address,
@@ -33,40 +26,43 @@ import {
   restoreInjected,
 } from "./session.js";
 import { discoverWallets } from "./injected.js";
-// fundOrder нужен ЛОКАЛЬНЫМ именем: export * из модуля ./funding.js« ниже только реэкспортирует, но не
-// создаёт переменную в этом модуле. Из-за этого fundOrderLive вызывал несуществующее имя и падал.
+// fundOrder needs a LOCAL name: `export * from ./funding.js` only re-exports and does not create a local
+// variable, so fundOrderLive called a missing name and crashed.
 import { fundOrder } from "./funding.js";
 export * from "./factory.js";
 export * from "./escrow.js";
 export * from "./funding.js";
-// ВНОСЯЩИЙ ПО ПОДПИСИ И РАЗРЕШЕНИЕ НА ТОКЕН. Форма подписи вносящего (evm/depositor.js) и вердикт о
-// разрешении по подписи (evm/permit.js) выходят через ТОТ ЖЕ шов движка: страница и SDK пользуются одним
-// кодом протокола, а не двумя похожими.
+// The depositor signature form (evm/depositor.js) and the permit verdict (evm/permit.js) go through the SAME
+// engine seam: the page and the SDK share one protocol code, not two lookalikes.
 export * from "./depositor.js";
 export * from "./permit.js";
+// THE ASYNCHRONOUS ROUTE, EXECUTED - through the same engine seam as the decision that chooses it. The page reaches
+// it through the bridge; the SDK carries the same module in its engine mirror (tools/build-sdk-engine.mjs).
+export * from "./asyncRoute.js";
+export * from "./asyncExec.js";
+// THE LIQUIDITY LEG OF A COMPOSED ROUTE (KyberSwap Limit Order) - through the same engine seam as the CoW leg,
+// so the page and the SDK carry one implementation each.
+export * from "./asyncLegs.js";
 
-// currentProvider - ПРОВАЙДЕР КОШЕЛЬКА НАРУЖУ, ЯДРУ: склейник отдаёт его адаптеру SDK (evm-wallet.mjs), чтобы
-// подпись шла тем же ключом, что и у страницы. Экранам он не нужен: они читают status()/isConnected().
+// currentProvider - the wallet provider goes OUT to the SDK core (evm-wallet.mjs) so signing uses the same
+// key as the page. Screens do not need it; they read status()/isConnected().
 export { address, balanceOf, chainIdOf, connect, disconnect, isConnected, refreshBalances, restore, status, subscribe, switchChain, currentProvider };
 export { connectInjected, restoreInjected };
-// ВАЖНО: это импорт, а не реэкспорт. Конструкция export { X } из модуля ...« только реэкспортирует имя и НЕ
-// создаёт его в этом модуле, а fundOrderLive ниже вызывает sendTransaction и readContract напрямую.
-// Ровно на этом уже падало дважды: сначала fundOrder, затем readContract - оба имени были доступны
-// снаружи, но не внутри файла.
+// IMPORTANT: this is an import, not a re-export. `export { X } from ...` only re-exports and does NOT create
+// a local name, while fundOrderLive uses sendTransaction/readContract directly - this already broke twice.
 import { sendTransaction, readContract, readReceipt, readCode } from "./session.js";
 export { sendTransaction, readContract, readReceipt, readCode };
 
-// Список браузерных кошельков в этом браузере (EIP-6963, с фолбэком на window.ethereum).
-// Пустой список - обычное дело: значит расширения нет, и остаётся WalletConnect.
+// The browser wallets available here (EIP-6963, falling back to window.ethereum). An empty list is normal:
+// no extension, so WalletConnect remains.
 export function wallets() {
   return discoverWallets();
 }
 
-// Балансы всех принимаемых токенов сети (нативный первым) - для экранов, которым нужен список.
+// Balances of all accepted tokens of the network (native first), for screens that need the list.
 
-// ИМИТАЦИЯ: настоящей транзакции не отправляем, потому что отправлять некуда - escrow-контракта
-// нет. Возвращаем поддельный хеш, чтобы состояние сделки осталось выводимым (см. docs/03).
-// В UI это сказано прямо: демка не двигает реальные деньги.
+// SIMULATION: no real transaction is sent (there is no escrow contract). A fake hash is returned so the
+// swap state stays derivable; the UI says plainly the demo moves no real money.
 export async function simulateEscrowFunding(tx) {
   await new Promise((r) => setTimeout(r, 900));
   const bytes = new Uint8Array(32);
@@ -75,31 +71,28 @@ export async function simulateEscrowFunding(tx) {
   return { hash, ...tx, simulated: true };
 }
 
-// БОЕВОЙ ПУТЬ ФОНДИРОВАНИЯ: настоящие транзакции в кошельке пользователя.
+// THE LIVE FUNDING PATH: real transactions in the user's wallet.
 //
-// Заменяет simulateEscrowFunding. Отличие принципиальное: симуляция выдумывала хеш, здесь уходят две
-// настоящие транзакции - createOrder в фабрику и lock(sealedHalf) в созданный эскроу.
+// Replaces simulateEscrowFunding. The difference is fundamental: the simulation invented a hash, here two
+// real transactions go out - createOrder to the factory and lock(sealedHalf) to the new escrow.
 //
-// Разделение обязанностей намеренное: криптография (половины, DLEQ, посылка) живёт в www/js/atomic/ и
-// сюда НЕ заглядывает. Эта функция получает уже готовые sealedCommitment и sealedHalf - то есть ровно то,
-// что уходит в контракт. Порядок вычислений задаёт вызывающий: сначала проверить сторону контрагента
-// (раздел 20.5), и только потом лочить.
+// Separation is deliberate: cryptography (halves, DLEQ, envelope) lives in www/js/atomic/ and does NOT reach
+// here. This function gets the ready sealedCommitment and sealedHalf - exactly what goes to the contract.
+// The caller sets the order of steps: verify the counterparty first, then lock.
 //
-// factory передаётся снаружи: адрес берётся из конфига сети тем, кто вызывает, чтобы здесь не заводить
-// второй источник правды об адресах.
-// ПОДПИСЬ ПРИВЕДЕНА К НОВОЙ СХЕМЕ, и это была не косметика: здесь оставались хешлок, обязательство и
-// посылка от прежнего устройства, а обязательств на половины и точек ed25519 - которые fundOrder ТРЕБУЕТ
-// и без которых падает - не было вовсе. То есть живой путь фондирования не мог пройти даже первый шаг:
-// вызов уходил дальше без четырёх обязательных полей. Ни синтаксис, ни проверки этого не видели, потому
-// что живой путь никем не запускается: он требует настоящего кошелька и подписи.
-// ЧЕТЫРЕ ПОЛЯ И ДВА СРОКА ЯВНО. Сроки приходят готовыми (readyBy, t1), а не считаются здесь от текущего
-// времени: они входят в контекст, к которому привязано доказательство, значит должны быть решены ДО него.
+// factory is passed in (the caller takes it from the network config) so there is no second source of truth
+// for addresses here.
+// THE SIGNATURE WAS BROUGHT TO THE NEW SCHEME: the old hashlock/commitment/envelope fields remained, while
+// the half commitments and ed25519 points that fundOrder REQUIRES were absent - so the live funding path
+// could not pass even the first step. Neither syntax nor checks saw this, because the live path is never run.
+// FOUR FIELDS AND TWO DEADLINES EXPLICITLY. The deadlines come ready (readyBy, t1), not computed from now:
+// they go into the context the proof binds to, so they must be fixed before it.
 export async function fundOrderLive({ factory, locker, claimer, commitHalfLocker, commitHalfClaimer, edPointLocker, edPointClaimer, edViewPointLocker, salt, amountWei, amountLabel, claimWindowSeconds = 3600, readyWindowSeconds = 14400, readyBy, t1, quote, depositorSignature, onStep }) {
   return fundOrder({
     factory,
-    quote,                         // подписанная котировка: несёт комиссию, адрес реестра и провайдера
-    // ПОДПИСЬ ВНОСЯЩЕГО НАД ДАЙДЖЕСТОМ КОТИРОВКИ (issue #97, части A/C). Есть - фондирование идёт путём
-    // createOrderAndFundByDepositor, и транзакцию вправе отправить кто угодно. Нет - прежний путь.
+    quote,                         // signed quote: carries the fee, registry address and provider
+    // THE DEPOSITOR SIGNATURE OVER THE QUOTE DIGEST. Present: funding goes via
+    // createOrderAndFundByDepositor and anyone may send the transaction. Absent: the old path.
     depositorSignature,
     locker,
     claimer,
@@ -108,16 +101,16 @@ export async function fundOrderLive({ factory, locker, claimer, commitHalfLocker
     edPointLocker,
     edPointClaimer,
     edViewPointLocker,
-    salt,                          // повтор фондирования обязан попасть в тот же адрес эскроу
-    amountLabel,                   // "0.03 ETH" вместо числа в wei на кнопке
+    salt,                          // retrying funding must land at the same escrow address
+    amountLabel,                   // "0.03 ETH" instead of the wei number on the button
     amountWei,
     claimWindowSeconds,
     readyWindowSeconds,
-    readyBy,                       // сроки, к которым уже привязано доказательство
+    readyBy,                       // deadlines the proof is already bound to
     t1,
     call: readContract,
     send: sendTransaction,
-    receipt: readReceipt,          // адрес эскроу берём из квитанции, а не из предсказания
+    receipt: readReceipt,          // the escrow address comes from the receipt, not from a prediction
     onStep,
   });
 }

package/engine/evm/injected.js

@@ -1,27 +1,22 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/injected.js for the SDK package.
-// Edit the source under www/js, then run: node tools/build-sdk-engine.mjs
-// tools/check-sdk-engine.mjs reddens on any drift, so a stale copy cannot ship silently.
+// Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
 // Everything below this header is identical to the source.
 
-// Браузерные кошельки: обнаружение по EIP-6963 и подключение по EIP-1193.
+// BROWSER WALLETS: detection by EIP-6963 and connection by EIP-1193.
+// WHY EIP-6963, NOT window.ethereum.isMetaMask. With two extensions installed, window.ethereum is "whoever was
+// last", and guessing by flags gives wrong names and icons. EIP-6963 solves this: a wallet announces itself with
+// an `eip6963:announceProvider` event (name, icon, provider), and the page requests it with `eip6963:requestProvider`.
+// So the wallet list is real and updates if the user installs an extension with the tab open.
+// window.ethereum stays as a fallback for old wallets; there the honest name is "Browser wallet".
+// NO STATE HERE: this module only finds providers and does the handshake. State and balances live in evm/session.js.
 //
-// ПОЧЕМУ EIP-6963, А НЕ window.ethereum.isMetaMask. При двух установленных расширениях
-// window.ethereum - это «кто успел последним», и угадывание по флагам даёт чужие имена и иконки:
-// пользователь видит «MetaMask», а подключается Rabby. EIP-6963 решает это стандартно: кошелёк
-// объявляет себя событием `eip6963:announceProvider` с именем, иконкой и своим провайдером, а
-// страница просит объявиться событием `eip6963:requestProvider`. Так список кошельков настоящий,
-// и он же обновляется, если пользователь поставил расширение при открытой вкладке.
 //
-// window.ethereum остаётся фолбэком для старых кошельков, которые 6963 ещё не умеют. В этом
-// случае честное имя - «Browser wallet»: назвать его MetaMask мы не имеем права, не проверив.
 //
-// Здесь НЕТ состояния: этот модуль только находит провайдеров и делает рукопожатие. Состояние,
-// балансы и смена сети живут в evm/session.js - общие для обоих коннекторов.
 
 const ANNOUNCE = "eip6963:announceProvider";
 const REQUEST = "eip6963:requestProvider";
 
-// Коды EIP-1193, которые важны на экране: отказ пользователя - это не ошибка приложения.
+// EIP-1193 codes that matter on screen: a user refusal is not an application error.
 export const USER_REJECTED = 4001;
 
 export function isUserRejection(error) {
@@ -30,7 +25,7 @@ export function isUserRejection(error) {
   return /rejected|denied|cancell?ed|closed by user/i.test(String((error && error.message) || error || ""));
 }
 
-// Человеческое имя для фолбэка: флаги - единственное, что есть у старых кошельков.
+// A human name for the fallback: flags are all the old wallets have.
 function fallbackName(eth) {
   if (!eth) return null;
   if (eth.isMetaMask) return "MetaMask";
@@ -41,9 +36,8 @@ function fallbackName(eth) {
   return "Browser wallet";
 }
 
-// Собрать список кошельков: сначала объявившиеся по EIP-6963, затем фолбэк window.ethereum.
-// timeoutMs нужен потому, что announceProvider - событие: без паузы список будет пустым даже при
-// установленном кошельке (у расширения свой темп инициализации).
+// Build the wallet list: first those announced by EIP-6963, then the window.ethereum fallback. timeoutMs is
+// needed because announceProvider is an event: without a pause the list would be empty even with a wallet installed.
 export function discoverWallets({ win = globalThis, timeoutMs = 250 } = {}) {
   const found = [];
   const seen = new Set();
@@ -70,7 +64,7 @@ export function discoverWallets({ win = globalThis, timeoutMs = 250 } = {}) {
   if (win && typeof win.addEventListener === "function") {
     win.addEventListener(ANNOUNCE, onAnnounce);
     if (typeof win.dispatchEvent === "function") {
-      // Просим объявиться; ответы придут асинхронно, поэтому ждём короткую паузу.
+      // We ask them to announce; answers arrive asynchronously, so we wait a short pause.
       win.dispatchEvent(new Event(REQUEST));
     }
   }
@@ -78,8 +72,8 @@ export function discoverWallets({ win = globalThis, timeoutMs = 250 } = {}) {
   return new Promise((resolve) => {
     const finish = () => {
       if (win && typeof win.removeEventListener === "function") win.removeEventListener(ANNOUNCE, onAnnounce);
-      // Фолбэк: старый кошелёк, который 6963 не умеет, но window.ethereum выставил.
-      // providers (массив) бывает, когда установлено несколько кошельков без поддержки 6963.
+      // Fallback: an old wallet that does not know 6963 but sets window.ethereum. providers (array) appears with
+      // several wallets without 6963 support.
       const legacy = win && win.ethereum;
       if (!found.length && legacy) {
         const list = Array.isArray(legacy.providers) && legacy.providers.length ? legacy.providers : [legacy];
@@ -94,12 +88,11 @@ export function discoverWallets({ win = globalThis, timeoutMs = 250 } = {}) {
   });
 }
 
-// Подписка на «кошелёк появился». Нужна, чтобы список в модалке не был снимком на момент открытия:
-// пользователь может поставить расширение, не перезагружая страницу.
+// Subscribe to "a wallet appeared". Needed so the modal list is not a snapshot at open time: the user may install
+// an extension without reloading.
 //
-// Работаем именно с самим объявлением, а не с повторным обнаружением: событие EIP-6963 несёт и имя,
-// и провайдер кошелька, а события не переигрываются - кошелёк, объявившийся до нашей подписки, при
-// повторном запросе ответит снова, но снимок всё равно был бы потерян. Так список только дополняется.
+// We work with the announcement itself, not a re-detection: the EIP-6963 event carries the name and provider, and
+// events are not replayed, so a wallet that announced before our subscription would be lost on a re-request. The list only grows.
 export function watchWallets(fn, { win = globalThis } = {}) {
   if (!win || typeof win.addEventListener !== "function") return () => {};
   const known = new Map();
@@ -120,16 +113,16 @@ export function watchWallets(fn, { win = globalThis } = {}) {
     publish();
   };
   win.addEventListener(ANNOUNCE, onAnnounce);
-  // Просим объявиться: кошельки, которые уже установлены, ответят прямо сейчас и попадут в список.
-  // Пустой список наружу не отдаём - иначе UI очищался бы просто потому, что кошельков нет.
+  // We ask them to announce: installed wallets answer right now and enter the list. An empty list is not handed
+  // out, else the UI would be cleared just because there are no wallets.
   if (typeof win.dispatchEvent === "function") win.dispatchEvent(new Event(REQUEST));
   return () => win.removeEventListener(ANNOUNCE, onAnnounce);
 }
 
-// Рукопожатие EIP-1193: просим аккаунты (здесь кошелёк спросит разрешение) и узнаём сеть.
+// EIP-1193 handshake: ask for accounts (here the wallet asks permission) and learn the network.
 export async function handshake(provider) {
   if (!provider || typeof provider.request !== "function") {
-    throw new Error("Этот кошелёк не умеет EIP-1193 (нет request)");
+    throw new Error("This wallet does not support EIP-1193 (no request)");
   }
   const accounts = await provider.request({ method: "eth_requestAccounts" });
   const address = Array.isArray(accounts) ? accounts[0] : null;
@@ -137,10 +130,9 @@ export async function handshake(provider) {
   return { address: address || null, chainId: Number(chainIdHex) || null };
 }
 
-// Тихая проверка «сайт уже разрешён этому кошельку» - для восстановления после перезагрузки.
-// eth_accounts НЕ показывает окно кошелька: пустой ответ значит «разрешения нет», и это нормальное
-// состояние, а не ошибка. Именно поэтому нельзя звать здесь eth_requestAccounts: страница при
-// загрузке не должна выкидывать окно подключения.
+// A silent check "the site is already allowed for this wallet" - for restoring after a reload. eth_accounts does
+// NOT show the wallet window: an empty answer means "no permission", a normal state, not an error. That is why
+// eth_requestAccounts must not be called here: the page must not pop a connect window on load.
 export async function silentAccounts(provider) {
   if (!provider || typeof provider.request !== "function") return [];
   try {
@@ -151,25 +143,25 @@ export async function silentAccounts(provider) {
   }
 }
 
-// Почему кошелёк мог не открыться - переводим код ошибки в понятную причину.
+// Why the wallet may not have opened - translate the error code into a plain reason.
 //
-// -32002 - самая частая причина «нажал, а окно не появилось»: у кошелька уже есть открытый
-// запрос (окно висит на другом экране/вкладке, или предыдущая попытка не завершена).
-export function explainInjectedError(e, label = "Кошелёк") {
+// -32002 is the most common cause of "pressed but no window": the wallet already has an open request (the window
+// hangs on another screen/tab, or the previous attempt did not finish).
+export function explainInjectedError(e, label = "Wallet") {
   const code = e && (e.code || (e.data && e.data.originalError && e.data.originalError.code));
   const message = String((e && e.message) || e);
   if (code === -32002 || /already pending|already processing/i.test(message)) {
     return (
       label +
-      ": в кошельке уже есть незавершённый запрос, поэтому новое окно не открылось. " +
-      "Открой расширение, заверши или отмени тот запрос и нажми снова."
+      ": the wallet already has a pending request, so a new window did not open. " +
+      "Open the extension, finish or cancel that request, then try again."
     );
   }
   if (/no provider|not connected|provider is disconnected|undefined is not a function/i.test(message)) {
-    return label + ": расширение не отвечает (браузер мог выгрузить его или страница открыта не там, где оно работает).";
+    return label + ": the extension is not responding (the browser may have unloaded it, or the page is not where it works).";
   }
   if (/user rejected|user denied|rejected by user/i.test(message) || code === 4001) {
-    return label + ": запрос отклонён в кошельке.";
+    return label + ": the request was rejected in the wallet.";
   }
   return label + ": " + message;
 }