Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions modules/abstract-eth/README.md
Original file line number Diff line number Diff line change
@@ -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": <number>,
"expireTime": <unix-timestamp>
}
```

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.
7 changes: 7 additions & 0 deletions modules/abstract-eth/src/abstractEthLikeNewCoins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<RecoveryInfo | OfflineVaultTxInfo>}
*/
Expand Down
Loading