Add EVM TypeScript vault depositor SDK

.github/workflows/main-pr.yml

@@ -12,6 +12,10 @@ jobs:
     name: Unit
     uses: ./.github/workflows/test-go.yml
 
+  typescript:
+    name: TypeScript
+    uses: ./.github/workflows/test-ts.yml
+
   integration:
     name: Integration
     uses: ./.github/workflows/test-integration.yml

.github/workflows/main-push.yml

@@ -12,6 +12,10 @@ jobs:
     name: Unit
     uses: ./.github/workflows/test-go.yml
 
+  typescript:
+    name: TypeScript
+    uses: ./.github/workflows/test-ts.yml
+
   integration:
     name: Integration
     uses: ./.github/workflows/test-integration.yml

.github/workflows/test-integration.yml

@@ -24,6 +24,13 @@ jobs:
           go-version-file: go.mod
           cache: true
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: sdk/ts/package-lock.json
+
       - name: Bring up devnet
         run: make devnet
 

.github/workflows/test-ts.yml

@@ -0,0 +1,41 @@
+name: Test (TypeScript)
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  unit:
+    name: TypeScript Unit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: sdk/ts/package-lock.json
+
+      - name: Install
+        run: npm ci
+        working-directory: sdk/ts
+
+      - name: Typecheck
+        run: npm run typecheck
+        working-directory: sdk/ts
+
+      - name: Build package
+        run: npm run build
+        working-directory: sdk/ts
+
+      - name: Unit tests
+        run: npm test
+        working-directory: sdk/ts
+
+      - name: Build demo
+        run: npm --workspace @yellow-org/evm-deposit-demo run build
+        working-directory: sdk/ts

.gitignore

@@ -4,3 +4,11 @@
 # Go workspace files
 go.work
 go.work.sum
+
+# Node.js dependencies and build output
+node_modules/
+dist/
+examples/*/dist/
+sdk/ts/node_modules/
+sdk/ts/dist/
+sdk/ts/examples/*/dist/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build lint test generate devnet devnet-down integration
+.PHONY: build lint test generate devnet devnet-evm devnet-down ts-deps integration
 
 build:
 	go build ./...
@@ -23,10 +23,18 @@ devnet:
 	docker compose -f devnet/docker-compose.yml up -d
 	go run ./devnet/wait
 
+devnet-evm:
+	docker compose -f devnet/docker-compose.yml up -d anvil
+	go run ./devnet/wait --networks anvil
+
 devnet-down:
 	docker compose -f devnet/docker-compose.yml down -v
 
-# Build-tagged blockchain flow tests (deposit + withdrawal per chain). Every
-# test self-provisions against the devnet — no setup, no env. See devnet/README.md.
-integration:
+ts-deps:
+	npm --prefix sdk/ts ci
+
+# Blockchain flow tests against the devnet. Go tests cover deposit + withdrawal
+# per chain; the TS suite covers EVM deposits. See devnet/README.md.
+integration: ts-deps
 	go test -tags integration ./pkg/blockchain/... -v
+	npm --prefix sdk/ts run test:integration:evm

devnet/README.md

@@ -7,26 +7,31 @@ withdrawal test runs the whole *k-of-n* quorum in-process — it holds N local
 `sign.KeySigner`s and drives `Pack → Validate → Sign → Merge → Submit →
 VerifyExecution` itself, so no p2p mesh is needed.
 
+The TypeScript EVM SDK integration test lives under `sdk/ts/test` and runs
+through the same `make integration` target.
+
 ## Run
 
 ```sh
 make devnet        # anvil + bitcoind + rippled + solana-test-validator; blocks until all answer RPC
-make integration   # go test -tags integration ./pkg/blockchain/...
+npm --prefix sdk/ts ci
+make integration   # Go blockchain integrations + TS EVM integration
 make devnet-down
 ```
 
 `make devnet` returns only once every node answers (the `devnet/wait` probe).
-`make integration` then needs **no setup and no env** — every test
-self-provisions against the devnet and is **idempotent**: each run uses fresh
-keys / accounts / a freshly-deployed contract, so re-running is a clean run.
-Only each node's funder persists (anvil account 0, the bitcoind coinbase
+After Node dependencies are installed, `make integration` needs **no env**. The
+tests self-provision against the devnet and are **idempotent**: each run uses
+fresh keys / accounts / a freshly-deployed contract, so re-running is a clean
+run. Only each node's funder persists (anvil account 0, the bitcoind coinbase
 wallet, the XRPL genesis master).
 
 ## What each test provisions
 
 - **EVM** — deploys a fresh `Custody` vault over N freshly-generated signer
   keys (funded from anvil account 0), deposits native ETH, then runs the quorum
-  withdrawal.
+  withdrawal. The TypeScript EVM integration test also deploys fresh `Custody`
+  and `MockERC20` contracts and runs native ETH + ERC-20 deposit coverage.
 - **BTC** — creates a legacy wallet, mines to maturity, generates a fresh vault
   + depositor, watch-imports their addresses, funds the depositor, deposits to
   the per-account P2WSH address, then runs the quorum withdrawal (mining to

devnet/wait/main.go

@@ -6,9 +6,11 @@ package main
 import (
 	"bytes"
 	"context"
+	"flag"
 	"fmt"
 	"net/http"
 	"os"
+	"strings"
 	"time"
 )
 
@@ -21,6 +23,13 @@ type probe struct {
 }
 
 func main() {
+	networks := flag.String("networks", "", "comma-separated devnet networks to wait for: anvil,bitcoind,rippled,solana")
+	flag.Parse()
+	if flag.NArg() > 0 {
+		fmt.Fprintf(os.Stderr, "devnet: unexpected positional arguments: %s\n", strings.Join(flag.Args(), " "))
+		os.Exit(2)
+	}
+
 	probes := []probe{
 		{name: "anvil", url: envOr("EVM_RPC_URL", "http://127.0.0.1:8545"),
 			body: `{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}`},
@@ -33,9 +42,15 @@ func main() {
 			body: `{"jsonrpc":"2.0","id":1,"method":"getHealth"}`},
 	}
 
+	selected, err := selectProbes(probes, *networks, flagWasSet("networks"))
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "devnet: %v\n", err)
+		os.Exit(2)
+	}
+
 	deadline := time.Now().Add(90 * time.Second)
 	client := &http.Client{Timeout: 3 * time.Second}
-	for _, p := range probes {
+	for _, p := range selected {
 		if err := waitOne(client, p, deadline); err != nil {
 			fmt.Fprintf(os.Stderr, "devnet: %s not ready: %v\n", p.name, err)
 			os.Exit(1)
@@ -44,6 +59,45 @@ func main() {
 	}
 }
 
+func selectProbes(probes []probe, networks string, specified bool) ([]probe, error) {
+	if !specified {
+		return probes, nil
+	}
+
+	byName := make(map[string]probe, len(probes))
+	names := make([]string, 0, len(probes))
+	for _, p := range probes {
+		byName[p.name] = p
+		names = append(names, p.name)
+	}
+
+	parts := strings.Split(networks, ",")
+	selected := make([]probe, 0, len(parts))
+	for _, part := range parts {
+		name := strings.TrimSpace(part)
+		if name == "" {
+			return nil, fmt.Errorf("--networks must contain non-empty names from: %s", strings.Join(names, ","))
+		}
+		p, ok := byName[name]
+		if !ok {
+			return nil, fmt.Errorf("unsupported network %q; supported values: %s", name, strings.Join(names, ","))
+		}
+		selected = append(selected, p)
+	}
+
+	return selected, nil
+}
+
+func flagWasSet(name string) bool {
+	wasSet := false
+	flag.Visit(func(f *flag.Flag) {
+		if f.Name == name {
+			wasSet = true
+		}
+	})
+	return wasSet
+}
+
 func waitOne(client *http.Client, p probe, deadline time.Time) error {
 	var last error
 	for time.Now().Before(deadline) {

devnet/wait/main_test.go

@@ -0,0 +1,73 @@
+package main
+
+import "testing"
+
+func TestSelectProbesDefaultAll(t *testing.T) {
+	probes := testProbes()
+
+	got, err := selectProbes(probes, "", false)
+	if err != nil {
+		t.Fatalf("selectProbes returned error: %v", err)
+	}
+	if len(got) != len(probes) {
+		t.Fatalf("got %d probes, want %d", len(got), len(probes))
+	}
+	for i := range probes {
+		if got[i].name != probes[i].name {
+			t.Fatalf("probe %d = %q, want %q", i, got[i].name, probes[i].name)
+		}
+	}
+}
+
+func TestSelectProbesSubset(t *testing.T) {
+	got, err := selectProbes(testProbes(), "anvil,solana", true)
+	if err != nil {
+		t.Fatalf("selectProbes returned error: %v", err)
+	}
+
+	want := []string{"anvil", "solana"}
+	assertProbeNames(t, got, want)
+}
+
+func TestSelectProbesTrimsNames(t *testing.T) {
+	got, err := selectProbes(testProbes(), " anvil , rippled ", true)
+	if err != nil {
+		t.Fatalf("selectProbes returned error: %v", err)
+	}
+
+	want := []string{"anvil", "rippled"}
+	assertProbeNames(t, got, want)
+}
+
+func TestSelectProbesRejectsEmptyName(t *testing.T) {
+	if _, err := selectProbes(testProbes(), "anvil,", true); err == nil {
+		t.Fatal("expected empty network name to fail")
+	}
+}
+
+func TestSelectProbesRejectsUnsupportedName(t *testing.T) {
+	if _, err := selectProbes(testProbes(), "anvil,ethereum", true); err == nil {
+		t.Fatal("expected unsupported network name to fail")
+	}
+}
+
+func testProbes() []probe {
+	return []probe{
+		{name: "anvil"},
+		{name: "bitcoind"},
+		{name: "rippled"},
+		{name: "solana"},
+	}
+}
+
+func assertProbeNames(t *testing.T, probes []probe, want []string) {
+	t.Helper()
+	if len(probes) != len(want) {
+		t.Fatalf("got %d probes, want %d", len(probes), len(want))
+	}
+	for i := range want {
+		if probes[i].name != want[i] {
+			t.Fatalf("probe %d = %q, want %q", i, probes[i].name, want[i])
+		}
+	}
+}

pkg/p2p/pubsub/pubsub_test.go

@@ -59,9 +59,7 @@ func TestPubSub_FinalizedWithdrawal(t *testing.T) {
 			if fw.WithdrawalID != want.WithdrawalID || fw.EntryIndex != want.EntryIndex {
 				t.Fatalf("delivered %+v, want %+v", fw.Header(), want.Header())
 			}
-			if m := follower.Metrics().Snapshot(); m.Delivered != 1 {
-				t.Errorf("Delivered = %d, want 1", m.Delivered)
-			}
+			waitDelivered(t, follower, 1)
 			return
 		case <-ticker.C:
 			continue
@@ -91,3 +89,22 @@ func connect(t *testing.T, from, to host.Host) {
 		t.Fatalf("connect: %v", err)
 	}
 }
+
+func waitDelivered(t *testing.T, follower *Follower[core.FinalizedWithdrawal, *core.FinalizedWithdrawal], want uint64) {
+	t.Helper()
+	deadline := time.After(time.Second)
+	ticker := time.NewTicker(10 * time.Millisecond)
+	defer ticker.Stop()
+
+	for {
+		if got := follower.Metrics().Snapshot().Delivered; got == want {
+			return
+		}
+		select {
+		case <-deadline:
+			got := follower.Metrics().Snapshot().Delivered
+			t.Fatalf("Delivered = %d, want %d", got, want)
+		case <-ticker.C:
+		}
+	}
+}

sdk/ts/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yellow Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.