diff --git a/modules/abstract-eth/README.md b/modules/abstract-eth/README.md index 856c0af47c..4d25e1ab81 100644 --- a/modules/abstract-eth/README.md +++ b/modules/abstract-eth/README.md @@ -1 +1,57 @@ # BitGo abstract-eth + +Abstract base implementation for EVM-compatible coins (ETH, ETC, Polygon, OP-ETH, Arb-ETH, etc.). + +## EVM Cross-Chain Recovery + +EVM cross-chain recovery allows funds accidentally sent to a wrong EVM chain to be +recovered. The recovery flow produces an unsigned (cold/custody wallet) or half-signed +(hot wallet) transaction JSON that must be signed by the appropriate trust team before +it can be broadcast. + +### Trust Team Signing Responsibility + +For backing wallets under EVM cross-chain recovery: + +| Step | Responsible party | Action | +|------|-------------------|--------| +| 1 | Support engineer | Generate unsigned recovery JSON via `recoverEthLikeforEvmBasedRecovery` and provide it to SD Trust | +| 2 | **SD (South Dakota) Trust** | Sign the unsigned JSON using the **Singapore key shards** and return the half-signed JSON | +| 3 | Support engineer | Broadcast the half-signed transaction | + +**Key points to avoid ambiguity:** + +- **SD Trust** (South Dakota) is the team that receives the unsigned JSON and performs + the signing operation. +- **SG Custody** (Singapore) does **not** sign directly and will not see a signing + request appear in their reports. SG Custody's role is to hold the key shards that + SD Trust must select when signing. +- SD Trust must explicitly select the **Singapore key shards** when performing the + signing step. Using other shards will produce an invalid signature for wallets + custodied under Singapore. + +### Required Fields in the Unsigned JSON + +The unsigned transaction JSON must include the following fields before it is sent to +SD Trust for signing: + +```json +{ + "nextContractSequenceId": , + "expireTime": +} +``` + +If these fields are missing, SD Trust's signing tool will return an error. The +`expireTime` should be set to a future Unix timestamp (typically one week out). + +### Half-Signed JSON Validation + +After SD Trust returns the half-signed JSON, verify that `halfSigned.txHex` is +present. If it is missing the broadcast step will fail with: + +``` +Error: Invalid half signed recovery file, missing halfSigned.txHex +``` + +In that case, request a new signing from SD Trust using the updated unsigned JSON. diff --git a/modules/abstract-eth/src/abstractEthLikeNewCoins.ts b/modules/abstract-eth/src/abstractEthLikeNewCoins.ts index 3effa6a05a..d6648ce5c5 100644 --- a/modules/abstract-eth/src/abstractEthLikeNewCoins.ts +++ b/modules/abstract-eth/src/abstractEthLikeNewCoins.ts @@ -1728,6 +1728,13 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin { * half-signed (for hot wallet) evm cross chain recovery transaction with * same expected arguments as recover method. * This helps recover funds from evm based wrong chain. + * + * Signing responsibility for backing wallets: + * - SD (South Dakota) Trust is responsible for signing the unsigned JSON + * produced by this method and returning the half-signed JSON to support. + * - SD Trust must use the Singapore key shards when signing. + * - SG (Singapore) Custody Trust does not sign directly; its role is + * only to hold the relevant key shards used by SD Trust. * @param {RecoverOptions} params * @returns {Promise} */