feat(sdk): Add gasless deposit type exports and comprehensive test coverage by lrsaturnino · Pull Request #915 · threshold-network/tbtc-v2

lrsaturnino · 2025-11-05T05:05:04Z

Summary

Implements SDK type exports and test infrastructure for gasless tBTC deposits feature, where relayer backend pays all gas fees for deposit reveals.

This PR establishes the foundation for gasless deposits by adding type exports, comprehensive test coverage, and documentation.

Changes

Type System

Export GaslessDepositResult interface for deposit initialization results
Export GaslessRevealPayload interface for backend relay submission
Add type export validation tests to prevent regressions

Test Coverage

Comprehensive unit tests for initiateGaslessDeposit (L1 and L2 paths)
Comprehensive unit tests for buildGaslessRelayPayload (owner encoding)
Error handling tests for unsupported chains and uninitialized contracts
Validation tests for Bitcoin recovery address formats (P2PKH, P2WPKH)
Chain-specific owner encoding tests (bytes32 for L1, address for L2)

Documentation

JSDoc documentation for gasless deposit helper methods
Document depositKey computation happens on backend (Bitcoin hash256)
Document chain-specific owner encoding requirements

Code Quality

Remove unused test variables
Fix all linting errors (6 to 0)
All 683 tests passing with zero regressions

Technical Details

Owner Encoding:

L1 deposits: bytes32 format (left-padded address)
L2 deposits: address format (20 bytes extracted from extraData)

Bitcoin Algorithm:

depositKey computation uses Bitcoin hash256 (double-SHA256)
Backend responsibility, SDK provides raw transaction data

Files Changed

typescript/src/services/deposits/deposits-service.ts - JSDoc documentation
typescript/test/services/deposits.test.ts - Comprehensive test suite
typescript/test/exports/gasless-types.test.ts - Type export validation
typescript/api-reference/ - Generated documentation

Checklist

…verage Implements SDK type exports and test infrastructure for gasless tBTC deposits feature, where relayer backend pays all gas fees for deposit reveals. Type System: - Export GaslessDepositResult interface for deposit initialization results - Export GaslessRevealPayload interface for backend relay submission - Add type export validation tests to prevent regressions Test Coverage: - Add comprehensive unit tests for initiateGaslessDeposit (L1 and L2 paths) - Add comprehensive unit tests for buildGaslessRelayPayload (owner encoding) - Verify error handling for unsupported chains and uninitialized contracts - Validate Bitcoin recovery address formats (P2PKH, P2WPKH) - Test chain-specific owner encoding (bytes32 for L1, address for L2) Documentation: - Add JSDoc documentation to gasless deposit helper methods - Document depositKey computation happens on backend (Bitcoin hash256) - Document chain-specific owner encoding requirements Code Quality: - Remove unused test variables - Fix all linting errors - Ensure all 683 tests pass with zero regressions This implementation ensures proper Bitcoin hash256 usage and chain-specific encoding for gasless deposit functionality.

piotr-roslaniec

Just some nitpicks/questions

piotr-roslaniec · 2025-11-05T08:51:22Z

typescript/src/services/deposits/deposits-service.ts

+
+    // Step 3: Determine owner encoding based on chain
+    // L1 contracts expect bytes32 owner (32 bytes), L2 contracts expect address (20 bytes)
+    let destinationOwner: string


Would ethers.utils.isHexString be useful here?

yeah, that makes sense. We're doing manual validation and ethers already handles edge cases, so using it would be cleaner and less error-prone.

Thank you for the suggestion! However, ethers.utils.isHexString would be redundant here since the Hex class constructor already validates hex format with regex, ensuring receipt.extraData.toPrefixedString() always returns valid hex strings.

piotr-roslaniec · 2025-11-05T08:52:34Z

typescript/src/services/deposits/deposits-service.ts

+   * Target chain name for the deposit.
+   * Can be "L1" or any L2 chain name (e.g., "Arbitrum", "Base", "Optimism").
+   */
+  destinationChainName: string


Consider type GaslessDestination = 'L1' | DestinationChainName

I like that. It makes the intent clearer than just string and gives better autocomplete. Could we also add a runtime check or validation function to ensure it's actually 'L1' or a valid DestinationChainName? Otherwise TypeScript won't catch it at runtime if someone passes a wrong string.

Good catch - implemented in #965336f2

typescript/src/lib/ethereum/constants.ts

…dd override setter in DepositsService

…d update error expectation

…-resolve + setter)

…normalization Add chain validation and backend-compatible chain name normalization for gasless tBTC deposits to improve error handling and ensure seamless backend integration. Changes: - Update testnet NativeBTCDepositor address to deployed Sepolia contract - Add SUPPORTED_GASLESS_CHAINS constant to validate deposit chains early - Implement chain name normalization in buildGaslessRelayPayload (SDK accepts capitalized names, backend receives lowercase) - Enhance JSDoc documentation with supported chains and capitalization - Add comprehensive test coverage for validation and normalization Technical details: - Supported chains: L1, Arbitrum, Base, Sui, StarkNet - Solana excluded due to different architecture - Chain names normalized to lowercase except "L1" - Early validation prevents runtime errors with clear messages Test results: 55 passing, 0 failing

…supported chains Update GaslessRevealPayload documentation to accurately reflect chain-specific parameter types based on deployed contract ABIs: - L1, Sui, StarkNet use bytes32 (32-byte hex) - Arbitrum, Base use address (20-byte hex) Add note about backend automatic padding for chains requiring bytes32 format.

Introduce GaslessDestination type to provide compile-time type safety for destination chain names in gasless deposit operations. Changes: - Add GaslessDestination type: 'L1' | DestinationChainName - Update GaslessDepositResult.destinationChainName from string to GaslessDestination - Update test imports and type annotations for type safety This prevents invalid chain names at compile time while maintaining runtime validation for unsupported chains. Type resolves to: 'L1' | 'Arbitrum' | 'Base' | 'Solana' | 'StarkNet' | 'Sui'

@param

Add missing JSDoc documentation to fix ESLint valid-jsdoc errors: - setNativeBTCDepositor: added @param and @returns tags - resolveNativeBTCDepositorFromNetwork: added @returns tag Applied Prettier code formatting to improve readability. Regenerated TypeDoc API reference documentation.

Updates CI workflows and package requirements to use Node.js 20.x to resolve dependency incompatibility with @solana/codecs-numbers@2.3.0 which requires Node.js >=20.18.0. Changes: - Update GitHub Actions workflows to use Node.js 20.x - Update package.json engines field to require Node.js >=20 - Resolves installation failures in CI/CD pipeline All TypeScript SDK tests verified passing with Node 20.19.0.

piotr-roslaniec · 2025-11-07T08:11:57Z

typescript/src/services/deposits/deposits-service.ts

+    const receipt = await this.generateDepositReceipt(
+      bitcoinRecoveryAddress,
+      depositor,
+      undefined


Not sure how to address this, but maybe there is a way to avoid passing undefined here and resolve this field earlier instead of using receipt.extraData, see line 591

thanks for the review - fixed.

typescript/src/services/deposits/deposits-service.ts

piotr-roslaniec · 2025-11-07T08:14:23Z

typescript/src/services/deposits/deposits-service.ts

+    if (
+      !BitcoinScriptUtils.isP2PKHScript(recoveryOutputScript) &&
+      !BitcoinScriptUtils.isP2WPKHScript(recoveryOutputScript)
+    ) {
+      throw new Error("Bitcoin recovery address must be P2PKH or P2WPKH")
+    }


We have some similar logic on line 738, maybe we should validate once (early) or deduplicate this logic into a utility if validating once is not practical

piotr-roslaniec

Just some comments/nitpicks

Fixed critical bug where L1 gasless deposits would send tBTC to the NativeBTCDepositor contract instead of the user's address. Changes: - Add depositOwner parameter to initiateGaslessDeposit() method - Encode depositOwner as bytes32 in L1 deposits via extraData - Simplify buildGaslessRelayPayload() to always require extraData - Update all test cases to pass depositOwner parameter - Remove unused encodeOwnerAddressAsBytes32() helper method The depositOwner is now properly embedded in the deposit script's extraData field for both L1 and L2 deposits, ensuring tBTC is transferred to the correct recipient address.

Co-authored-by: piotr-roslaniec <39299780+piotr-roslaniec@users.noreply.github.com>

Remove redundant validation logic in initiateGaslessDeposit that was duplicating the validation already performed in generateDepositReceipt. Changes: - Remove duplicate Bitcoin recovery address validation (lines 415-426) - Fix buildGaslessRelayPayload to handle missing extraData for L1 deposits - Encode depositor address as bytes32 when extraData is absent for L1 - Maintain strict extraData requirement for L2 cross-chain deposits Benefits: - Eliminates duplicate RPC call to getNetwork() (~100-200ms savings) - Single source of truth for address validation in generateDepositReceipt - Consistent validation flow across all deposit methods - Better L1 backward compatibility with optional extraData All 693 tests passing, including 26 gasless deposit tests.

…network/tbtc-v2 into feat/gasless-deposits

Add type assertions to test cases that intentionally use invalid chain names for error handling validation. This fixes TypeScript compilation errors while preserving the runtime validation tests. Changes: - test/services/deposits.test.ts: Add 'as GaslessDestination' type assertions to 5 test cases that verify rejection of invalid chain names (Optimism, arbitrum, InvalidChain, empty string) - api-reference/classes/DepositsService.md: Update parameter type documentation from 'string' to 'GaslessDestination' The type assertions allow TypeScript to compile while the tests still properly validate runtime error handling for unsupported chain names.

This commit fixes a critical bug in the gasless deposit flow where all L2 chains were receiving 20-byte Ethereum addresses, which is incorrect for non-EVM chains like Sui and StarkNet that require 32-byte addresses. Changes: - Add EVM_L2_CHAINS constant to identify EVM-compatible L2s (Arbitrum, Base) - Add isEVML2Chain() helper method for chain type detection - Update buildGaslessRelayPayload() to use chain-specific owner extraction: - EVM L2s (Arbitrum, Base): Extract 20-byte address from 32-byte extraData - Non-EVM L2s (Sui, StarkNet): Use full 32-byte extraData as owner - Fix existing tests to use correct 32-byte fixtures for non-EVM chains - Add comprehensive test coverage for all chain types and edge cases - Improve JSDoc documentation for gasless deposit methods This ensures deposits to Sui and StarkNet chains will use the correct address format, preventing deposit failures on non-EVM L2 chains.

lrsaturnino requested review from RobertoMSousa and piotr-roslaniec November 5, 2025 05:05

piotr-roslaniec previously approved these changes Nov 5, 2025

View reviewed changes

feat(sdk): auto-resolve NativeBTCDepositor from Bitcoin network and a…

4b64c87

…dd override setter in DepositsService

piotr-roslaniec dismissed their stale review via 4b64c87 November 5, 2025 20:54

piotr-roslaniec and others added 8 commits November 5, 2025 22:00

test(sdk): cover NativeBTCDepositor auto-resolve, setter override, an…

e7bf109

…d update error expectation

test(sdk): fix mainnet auto-resolve test to use mainnet P2PKH address

b20f4ae

docs(sdk): regenerate API reference for DepositsService changes (auto…

c85656d

…-resolve + setter)

lrsaturnino requested review from jose-compu and piotr-roslaniec November 7, 2025 05:21

piotr-roslaniec reviewed Nov 7, 2025

View reviewed changes

typescript/src/services/deposits/deposits-service.ts Outdated Show resolved Hide resolved

piotr-roslaniec reviewed Nov 7, 2025

View reviewed changes

piotr-roslaniec previously approved these changes Nov 7, 2025

View reviewed changes

lrsaturnino dismissed piotr-roslaniec’s stale review via 7c321a9 November 8, 2025 05:03

lrsaturnino and others added 4 commits November 8, 2025 00:11

Update typescript/src/services/deposits/deposits-service.ts

dbc35f5

Co-authored-by: piotr-roslaniec <39299780+piotr-roslaniec@users.noreply.github.com>

Merge branch 'feat/gasless-deposits' of https://github.com/threshold-…

182add9

…network/tbtc-v2 into feat/gasless-deposits

lrsaturnino requested a review from piotr-roslaniec November 8, 2025 05:43

RobertoMSousa approved these changes Nov 11, 2025

View reviewed changes

piotr-roslaniec previously approved these changes Nov 15, 2025

View reviewed changes

lrsaturnino dismissed piotr-roslaniec’s stale review via ac56381 November 22, 2025 04:47

lrsaturnino requested a review from piotr-roslaniec November 22, 2025 04:47

piotr-roslaniec approved these changes Nov 22, 2025

View reviewed changes

Conversation

lrsaturnino commented Nov 5, 2025

Summary

Changes

Type System

Test Coverage

Documentation

Code Quality

Technical Details

Files Changed

Checklist

Uh oh!

piotr-roslaniec left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrsaturnino Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

piotr-roslaniec left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lrsaturnino Nov 7, 2025 •

edited

Loading