ENG-505 [DRAFT] local development setup

.gitignore

@@ -66,6 +66,6 @@ tmp/
 
 # Output directory
 out/
-data/
+storage/
 logs/
-storage/
+data/

DEPOSIT_SETUP_SUMMARY.md

@@ -0,0 +1,106 @@
+# Deposit Testing Setup Summary
+
+## Current Situation
+
+✅ **Bridge Contract Deployed**: `0xc7BC782Da1AAb7ee5985aC94C575f374FA4C75e5`
+✅ **Deposit Data Generated**: Ready in `deposit-data/` directory  
+✅ **Wallet Exists**: Registered in WalletRegistry
+
+❌ **Issue**: Wallet was created BEFORE Bridge deployment
+❌ **Issue**: Bridge is not set as walletOwner
+❌ **Result**: Wallet state in Bridge is "Unknown" (0), needs to be "Live" (1)
+
+## Why Deposits Fail
+
+The error "Wallet must be in Live state" occurs because:
+- Bridge contract tracks wallet state separately from WalletRegistry
+- When a wallet is created, WalletRegistry calls `walletOwner.__ecdsaWalletCreatedCallback()`
+- Bridge implements this callback and registers the wallet internally
+- Your wallet was created before Bridge existed, so Bridge never received the callback
+
+## Solutions
+
+### Option 1: Create New Wallet (Recommended for Full Testing)
+
+**Prerequisites**: Bridge must be set as walletOwner
+
+1. **Set Bridge as walletOwner**:
+   ```bash
+   # Fund governance first
+   GOVERNANCE="0x1bef6019c28a61130c5c04f6b906a16c85397cea"
+   ACCOUNT=$(cast rpc eth_accounts --rpc-url http://localhost:8545 | jq -r '.[0]')
+   cast send $GOVERNANCE --value $(cast --to-wei 1 ether) --rpc-url http://localhost:8545 --unlocked --from $ACCOUNT
+
+   # Begin update
+   BRIDGE="0xc7BC782Da1AAb7ee5985aC94C575f374FA4C75e5"
+   WR_GOV="0x1bef6019c28a61130c5c04f6b906a16c85397cea"
+   cast send $WR_GOV "beginWalletOwnerUpdate(address)" $BRIDGE \
+     --rpc-url http://localhost:8545 --unlocked --from $GOVERNANCE
+
+   # Wait 60 seconds, then finalize
+   cast send $WR_GOV "finalizeWalletOwnerUpdate()" \
+     --rpc-url http://localhost:8545 --unlocked --from $GOVERNANCE
+   ```
+
+2. **Request new wallet**:
+   ```bash
+   ./scripts/request-new-wallet.sh
+   ```
+
+3. **Wait for DKG** (check logs or use `./scripts/wait-for-dkg-completion.sh`)
+
+4. **Verify wallet is Live in Bridge**:
+   ```bash
+   ./check-wallet-bridge-status.sh
+   ```
+
+5. **Generate new deposit data**:
+   ```bash
+   ./scripts/emulate-deposit.sh
+   ```
+
+6. **Reveal deposit**:
+   ```bash
+   ./reveal-deposit.sh
+   ```
+
+### Option 2: Use Unit Tests (Works Now!)
+
+Test deposit logic without contract setup:
+
+```bash
+# Test deposit script generation
+go test -v ./pkg/tbtc -run TestDeposit_Script
+
+# Test deposit sweep action
+go test -v ./pkg/tbtc -run TestDepositSweepAction_Execute
+
+# Test deposit finding logic
+go test -v ./pkg/tbtcpg -run TestDepositSweepTask_FindDepositsToSweep
+```
+
+### Option 3: Manual Bridge Registration (If Possible)
+
+If you can modify Bridge contract or have admin access, you could manually register the wallet. However, `registerNewWallet` can only be called by WalletRegistry, so this isn't straightforward.
+
+## Quick Reference
+
+**Check wallet status**: `./check-wallet-bridge-status.sh`
+**Generate deposit data**: `./scripts/emulate-deposit.sh`  
+**Reveal deposit**: `./reveal-deposit.sh`
+**Bridge address**: `0xc7BC782Da1AAb7ee5985aC94C575f374FA4C75e5`
+
+## Wallet States
+
+- **0**: Unknown (not registered in Bridge) ← Your current state
+- **1**: Live ✅ (can accept deposits)
+- **2**: MovingFunds
+- **3**: Closing
+- **4**: Closed
+- **5**: Terminated
+
+## Next Steps
+
+1. **For quick testing**: Use unit tests (Option 2) - works immediately
+2. **For full integration testing**: Set Bridge as walletOwner and create new wallet (Option 1)
+3. **For production**: Ensure Bridge is deployed and set as walletOwner BEFORE creating wallets

DEPOSIT_TESTING_GUIDE.md

@@ -0,0 +1,200 @@
+# Deposit Testing Guide
+
+## Current Status
+
+✅ **Bridge Stub Deployed**: `0xc0a2ee534F004a4ec2EFA541489acBD5ff4bBA99`  
+✅ **Wallets Created**: 2 wallets registered in WalletRegistry  
+❌ **Bridge State**: Unknown (Bridge stub doesn't track wallets)
+
+## Understanding Bridge Stub vs Full Bridge
+
+The **Bridge stub** (`solidity/tbtc-stub`) is minimal and only implements:
+- ✅ `requestNewWallet()` - triggers DKG
+- ✅ `__ecdsaWalletCreatedCallback()` - receives wallet creation callbacks
+- ❌ **Does NOT implement**: `revealDeposit()`, wallet tracking, deposit events
+
+The **Full Bridge** (`tmp/tbtc-v2/solidity`) implements complete deposit functionality.
+
+## Option 1: Test Deposits with Full Bridge Contract (Recommended)
+
+### Step 1: Deploy Full Bridge Contract
+
+```bash
+cd tmp/tbtc-v2/solidity
+npx hardhat deploy --network development --tags Bridge --reset
+```
+
+This will deploy the full Bridge contract with deposit functionality.
+
+### Step 2: Update WalletOwner to Full Bridge
+
+```bash
+cd ../../..
+cd solidity/ecdsa
+npx hardhat run scripts/init-wallet-owner.ts --network development
+```
+
+This will set the full Bridge as walletOwner (it will prefer Bridge stub, so you may need to manually update).
+
+### Step 3: Create New Wallet (if needed)
+
+Since wallets were created with Bridge stub, create a new wallet so the full Bridge receives the callback:
+
+```bash
+./scripts/request-new-wallet.sh
+```
+
+Wait for DKG to complete, then verify:
+
+```bash
+./check-all-wallets-bridge.sh
+```
+
+The new wallet should show "Bridge State: Live ✅" instead of "Unknown".
+
+### Step 4: Generate Deposit Data
+
+```bash
+./scripts/emulate-deposit.sh [depositor_address] [amount_satoshis]
+```
+
+Examples:
+```bash
+# Default: random depositor, 1 BTC
+./scripts/emulate-deposit.sh
+
+# Specify depositor and amount (0.5 BTC = 50000000 satoshis)
+./scripts/emulate-deposit.sh 0x7966C178f466B060aAeb2B91e9149A5FB2Ec9c53 50000000
+```
+
+This generates:
+- `deposit-data/deposit-data.json` - Complete deposit info
+- `deposit-data/funding-tx-info.json` - BitcoinTxInfo for revealDeposit()
+- `deposit-data/deposit-reveal-info.json` - DepositRevealInfo for revealDeposit()
+
+### Step 5: Reveal Deposit to Bridge
+
+**Using cast:**
+```bash
+BRIDGE=$(jq -r '.address' tmp/tbtc-v2/solidity/deployments/development/Bridge.json)
+ACCOUNT=$(cast rpc eth_accounts --rpc-url http://localhost:8545 | jq -r '.[0]')
+
+cast send "$BRIDGE" \
+  "revealDeposit((bytes4,bytes,bytes,bytes4),(uint32,bytes8,bytes20,bytes20,bytes4,address))" \
+  "$(cat deposit-data/funding-tx-info.json | jq -c .)" \
+  "$(cat deposit-data/deposit-reveal-info.json | jq -c .)" \
+  --rpc-url http://localhost:8545 \
+  --from "$ACCOUNT" \
+  --unlocked \
+  --gas-limit 500000
+```
+
+**Or use the reveal script (update Bridge address first):**
+```bash
+# Update reveal-deposit.sh with full Bridge address
+./reveal-deposit.sh
+```
+
+### Step 6: Monitor Deposit Events
+
+```bash
+BRIDGE=$(jq -r '.address' tmp/tbtc-v2/solidity/deployments/development/Bridge.json)
+
+cast logs --from-block 0 --to-block latest \
+  --address "$BRIDGE" \
+  "DepositRevealed(bytes32,bytes32,address,uint256,bytes20,bytes20,uint32,bytes32)" \
+  --rpc-url http://localhost:8545
+```
+
+### Step 7: Check Deposit Status
+
+```bash
+BRIDGE=$(jq -r '.address' tmp/tbtc-v2/solidity/deployments/development/Bridge.json)
+DEPOSIT_KEY=$(cast keccak "$(cat deposit-data/deposit-data.json | jq -r '.fundingTxHash')$(cat deposit-data/deposit-data.json | jq -r '.fundingOutputIndex')")
+
+cast call "$BRIDGE" "deposits(bytes32)" "$DEPOSIT_KEY" --rpc-url http://localhost:8545
+```
+
+## Option 2: Test Deposit Logic with Unit Tests (No Contracts Needed)
+
+Test the deposit logic without deploying contracts:
+
+```bash
+# Test deposit script generation
+go test -v ./pkg/tbtc -run TestDeposit_Script
+
+# Test deposit sweep logic
+go test -v ./pkg/tbtc -run TestDepositSweepAction_Execute
+
+# Test deposit finding
+go test -v ./pkg/tbtcpg -run TestDepositSweepTask_FindDepositsToSweep
+```
+
+## Option 3: Use Mock Bitcoin Chain (Advanced)
+
+For full end-to-end testing with mock Bitcoin transactions:
+
+```bash
+# Setup mock Bitcoin chain
+./setup-mock-bitcoin-chain.sh
+
+# Generate deposit with mock Bitcoin transaction
+./scripts/emulate-deposit.sh
+
+# Monitor deposit events
+./monitor-deposit-events.sh
+```
+
+## Quick Reference
+
+### Check Wallet Status
+```bash
+./check-all-wallets-bridge.sh
+```
+
+### Check Specific Wallet
+```bash
+WALLET_PKH="0xfed577fbba8e72ec01810e12b09d974d7ef6b6bf"
+BRIDGE=$(jq -r '.address' tmp/tbtc-v2/solidity/deployments/development/Bridge.json 2>/dev/null || echo "0xc0a2ee534F004a4ec2EFA541489acBD5ff4bBA99")
+
+cast call "$BRIDGE" "wallets(bytes20)" "$WALLET_PKH" --rpc-url http://localhost:8545
+```
+
+### Wallet States
+- **0**: Unknown (not registered in Bridge)
+- **1**: Live ✅ (can accept deposits)
+- **2**: MovingFunds
+- **3**: Closing
+- **4**: Closed
+- **5**: Terminated
+
+### Common Issues
+
+**Issue**: "Bridge State: Unknown (00)"  
+**Solution**: Bridge stub doesn't track wallets. Deploy full Bridge contract or use unit tests.
+
+**Issue**: "revealDeposit() not found"  
+**Solution**: Bridge stub doesn't implement this. Use full Bridge contract from `tmp/tbtc-v2`.
+
+**Issue**: "Wallet not found in Bridge"  
+**Solution**: Wallet was created before Bridge deployment. Create a new wallet after deploying Bridge.
+
+## Next Steps After Deposit Reveal
+
+1. **Operators detect deposit** - Wallet operators monitor for DepositRevealed events
+2. **Create sweep proposal** - Operators create a proposal to sweep the deposit
+3. **Sign and broadcast** - Operators sign and broadcast Bitcoin sweep transaction
+4. **Mint tBTC** - After Bitcoin confirmations, tBTC tokens are minted to depositor
+
+## Files Generated
+
+- `deposit-data/deposit-data.json` - Complete deposit information
+- `deposit-data/funding-tx-info.json` - BitcoinTxInfo structure
+- `deposit-data/deposit-reveal-info.json` - DepositRevealInfo structure
+
+## Additional Resources
+
+- `DEPOSIT_SETUP_SUMMARY.md` - Deposit setup summary
+- `deposit-processing-timeline.md` - Deposit processing timeline
+- `scripts/emulate-deposit.sh` - Deposit data generation script
+- `reveal-deposit.sh` - Deposit reveal script