🔍 CURRENT WALLET SYSTEM - COMPLETE ANALYSIS

Date: October 6, 2025
Purpose: Document what’s already implemented before starting Task 0.1

📊 EXECUTIVE SUMMARY

✅ GOOD NEWS: Much More Implemented Than Expected!

The wallet system has THREE parallel implementations:

✅ TON Wallet Generator v4R2 - FULLY WORKING (using tonutils-go)
⚠️ Placeholder Signers - Returns “not implemented” (in ton_tron_placeholders.go)
🔧 Trust Wallet Core Integration - Framework ready (via build tags)

Key Finding: We DON’T need to build TON from scratch! We need to: - Integrate existing TON generator into the Signer interface - Add TRON signer implementation - Optionally enable Trust Wallet Core for multi-chain support

🏗️ SYSTEM ARCHITECTURE (Current State)

Wallet Service Architecture
═══════════════════════════════════════════════════════════════

                    ┌──────────────────────────────────────┐
                    │   Wallet Service (gRPC/HTTP)         │
                    │   Port: 9092                          │
                    └──────────┬───────────────────────────┘
                               │
                ┌──────────────┼──────────────┐
                │              │              │
                ▼              ▼              ▼
        ┌───────────┐  ┌────────────┐  ┌──────────────┐
        │  Wallet   │  │ Wallet Root│  │   Signer     │
        │Repository │  │ Repository │  │   Factory    │
        └───────────┘  └────────────┘  └──────┬───────┘
                                              │
                              ┌───────────────┼────────────────┐
                              │               │                │
                              ▼               ▼                ▼
                    ┌──────────────┐  ┌────────────┐  ┌──────────────┐
                    │ TON Wallet   │  │Placeholder │  │ Trust Wallet │
                    │ Gen v4R2     │  │  Signers   │  │ Core (TWC)   │
                    │              │  │            │  │              │
                    │ ✅ WORKING   │  │ ⚠️ BROKEN  │  │ 🔧 OPTIONAL  │
                    └──────────────┘  └────────────┘  └──────────────┘

✅ WHAT’S ALREADY IMPLEMENTED

1. TON Wallet Generator v4R2 (COMPLETE & WORKING)

File: services/wallet/internal/wallet/domain/service/ton_wallet_generator_v4r2.go

Status: ✅ FULLY FUNCTIONAL

Features:

✅ BIP39 24-word mnemonic generation (via tonutils-go)
✅ ed25519 keypair generation
✅ v4R2 wallet contract address generation
✅ Bounceable/non-bounceable address forms
✅ Address validation
✅ Workchain 0 (mainnet) support
✅ Mnemonic encryption (AES-256-GCM + PBKDF2)
✅ Address derivation from existing mnemonic
✅ Integration with wallet service

Key Methods: - GenerateWallet(telegramID, label, isDefault) → Creates wallet + root - DeriveAddressFromMnemonic(mnemonic) → Derives address - ValidateTONAddress(address) → Validates TON address - GetAddressForms(address) → Returns bounceable/non-bounceable - EncryptData(data) / DecryptData(encrypted) → Secure storage

Current Usage:

// In wallet.service.go line 827+
func (w walletService) deriveAddress(ctx context.Context, telegramId int64, 
                                       network string, derivationPath string) {
    if network == "TON" {
        // ✅ Uses TON Wallet Generator v4R2
        mnemonicStr, _ := w.TonWalletGen.DecryptData(encryptedMnemonic)
        address, _ := w.TonWalletGen.DeriveAddressFromMnemonic(mnemonicStr)
        // ... generates proper TON addresses
    }
}

Dependencies:

github.com/xssnick/tonutils-go v1.14.1  ✅ Already in go.mod
golang.org/x/crypto v0.39.0              ✅ Already in go.mod

Test Status: - ✅ Unit tests exist (ton_wallet_generator_test.go) - ✅ Generates valid EQ…/UQ… addresses - ✅ Encryption/decryption working

2. Signer Interface & Factory (ARCHITECTURE READY)

Files: - services/wallet/internal/wallet/service/signer/interfaces.go - services/wallet/internal/wallet/service/signer/factory.go

Status: ✅ WELL-DESIGNED ARCHITECTURE

Interface Definition:

type Signer interface {
    Address(pub PubKey, chain Chain) (string, error)
    SignTx(chain Chain, priv PrivKey, payload []byte) ([]byte, error)
}

type Deriver interface {
    FromMnemonic(m string, path string, curve Curve) (PrivKey, PubKey, error)
}

Factory Pattern:

func NewSigner(chain Chain) Signer {
    enableTWC := os.Getenv("ENABLE_TWC_PLUGIN") == "true"
    if enableTWC {
        return newTWCSafe()  // Trust Wallet Core (optional)
    }
    switch chain {
    case Chain("TON"):
        return &tonSigner{}   // ⚠️ Currently returns "not implemented"
    case Chain("TRON"):
        return &tronSigner{}  // ⚠️ Currently returns "not implemented"
    }
}

Design Principles: - ✅ Clean interface segregation - ✅ Factory pattern for chain selection - ✅ Build tag support for optional TWC - ✅ Environment variable toggle

3. Trust Wallet Core Integration (FRAMEWORK READY)

Files: - services/wallet/internal/wallet/service/signer/twc/twc_signer_enabled.go - services/wallet/internal/wallet/service/signer/twc/twc_signer_disabled.go - services/wallet/internal/wallet/service/signer/twc_enabled_factory.go - services/wallet/internal/wallet/service/signer/twc_disabled_factory.go

Status: 🔧 BUILD TAG INFRASTRUCTURE COMPLETE

Build Tags System:

// twc_enabled_factory.go
//go:build twc
func twcFactory() Signer { return twcimpl.Enabled{} }

// twc_disabled_factory.go
//go:build !twc
func twcFactory() Signer { return nil }

CGO Setup (in twc_signer_enabled.go):

/*
#cgo CFLAGS: -I${SRCDIR}/wallet-core/include
#cgo LDFLAGS: -L${SRCDIR}/wallet-core/build -lTrustWalletCore ...
#include <TrustWalletCore/TWHDWallet.h>
*/
import "C"

Status: - ✅ Build tag infrastructure complete - ✅ CGO configuration ready - ⚠️ Implementation stub (returns “not implemented”) - ⚠️ Trust Wallet Core library not built yet

Usage:

# Build without TWC (default)
go build ./cmd/server

# Build with TWC (optional)
go build -tags twc ./cmd/server

# Enable at runtime
export ENABLE_TWC_PLUGIN=true

4. Additional Signer Implementation (PARTIAL)

File: services/wallet/internal/wallet/service/signer/signer.go

Status: ⚠️ PARTIAL IMPLEMENTATION

What Exists:

✅ TONSigner struct with ed25519 support
✅ NewTONSigner(privateKeyBytes) → Creates signer from key
✅ NewTONSignerFromSeed(seed) → Creates signer from seed  
✅ GenerateKeyPair() → Generates new keypair
✅ Sign(message) → Signs with ed25519
✅ Verify(message, signature) → Verifies signature
✅ SignTransaction(tx) → Signs TON transaction
⚠️ GenerateTONAddress() → SIMPLIFIED (not proper v4R2)

Issue with signer.go:

// Line 108 - SIMPLIFIED ADDRESS GENERATION
func GenerateTONAddress(publicKey []byte, bounceable bool) (string, error) {
    hash := sha256.Sum256(publicKey)  // ⚠️ TOO SIMPLE
    if bounceable {
        hash[0] |= 0x40
    }
    encoded := base64.URLEncoding.EncodeToString(hash[:])
    return "EQ" + encoded[:len(encoded)-2], nil
}

Problem: This does NOT generate proper v4R2 wallet addresses!
Solution: Use the TON Wallet Generator v4R2 instead (already working).

5. HD Wallet Support (BASIC)

File: packages/crypto/crypto.go

Status: ⚠️ PLACEHOLDER IMPLEMENTATION

What Exists:

⚠️ HDWallet struct
⚠️ NewHDWallet(mnemonic, passphrase)
⚠️ DerivePath(path) → BIP44 derivation
⚠️ BIP44 coin types defined (TON: 396, TRON: 195, ETH: 60)
⚠️ GenerateDerivationPath(network, account, change, index)

Issues:

// Line 292 - PLACEHOLDER HMAC
func hmacSHA512(key, data []byte) []byte {
    // Placeholder: ⚠️ WRONG
    hash := sha512.Sum512(append(key, data...))  
    return hash[:]
}

// Line 306 - PLACEHOLDER KEY DERIVATION
func privateToPublic(privateKey []byte) ([]byte, error) {
    // Placeholder: ⚠️ WRONG
    hash := sha256.Sum256(privateKey)
    return hash[:], nil
}

Recommendation: Don’t use packages/crypto/ HD wallet. Use proper libraries: - TON: tonutils-go (already working in TON Wallet Gen v4R2) - TRON: go-ethereum for secp256k1 + gotron-sdk

6. Placeholder Signers (THE PROBLEM)

File: services/wallet/internal/wallet/service/signer/ton_tron_placeholders.go

Status: ❌ BROKEN - RETURNS “NOT IMPLEMENTED”

type tonSigner struct{}

func (t *tonSigner) Address(pub PubKey, chain Chain) (string, error) {
    return "", errors.New("ton signer not implemented")  // ❌
}

func (t *tonSigner) SignTx(chain Chain, priv PrivKey, payload []byte) ([]byte, error) {
    return nil, errors.New("ton signer not implemented")  // ❌
}

type tronSigner struct{}

func (t *tronSigner) Address(pub PubKey, chain Chain) (string, error) {
    return "", errors.New("tron signer not implemented")  // ❌
}

func (t *tronSigner) SignTx(chain Chain, priv PrivKey, payload []byte) ([]byte, error) {
    return nil, errors.New("tron signer not implemented")  // ❌
}

This is Task 0.1 and 0.2!

🎯 CURRENT WALLET FLOW (Working)

Deposit Address Generation (TON) ✅

User requests TON wallet
        ↓
WalletService.EnsureDefaultWallet()
        ↓
TONWalletGeneratorV4R2.GenerateWallet()
        ↓
    1. Generate 24-word mnemonic (tonutils-go)
    2. Derive ed25519 keypair
    3. Generate v4R2 address (proper TON address)
    4. Encrypt mnemonic (AES-256-GCM)
    5. Store in database:
       - WalletRoot (encrypted mnemonic)
       - Wallet (address, public key, network)
        ↓
Return deposit address (EQ... format) ✅

Withdrawal Flow ⚠️ INCOMPLETE

User requests withdrawal
        ↓
Need to sign transaction
        ↓
factory.NewSigner("TON")
        ↓
Returns &tonSigner{} from placeholders
        ↓
Calls SignTx()
        ↓
ERROR: "ton signer not implemented" ❌

Problem: The Signer interface is used for withdrawals, but it returns errors!

🔥 THE DISCONNECT

Why Two Implementations?

TON Wallet Generator v4R2 (working):
- Purpose: Deposit wallet generation
- Used by: WalletService.EnsureDefaultWallet()
- Status: ✅ Fully functional
- Creates: Proper TON v4R2 addresses
Signer Interface (broken placeholders):
- Purpose: Transaction signing (withdrawals)
- Used by: Withdrawal flows, transaction processing
- Status: ❌ Returns “not implemented”
- Should: Sign transactions with private keys

The Gap:

┌─────────────────────────────────────────┐
│  DEPOSITS: ✅ Working                    │
│  Uses: TON Wallet Gen v4R2              │
│  Generates proper addresses              │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  WITHDRAWALS: ❌ Broken                  │
│  Uses: Signer interface                  │
│  Returns: "not implemented"              │
└─────────────────────────────────────────┘

📋 TASK 0.1 - WHAT WE ACTUALLY NEED TO DO

DON’T:

❌ Reimplement TON wallet generation (already works!)
❌ Rewrite mnemonic generation (tonutils-go works!)
❌ Rewrite address derivation (v4R2 generator works!)

DO:

✅ Bridge the gap between TON Wallet Gen and Signer interface
✅ Implement tonSigner.Address() using TON Wallet Gen v4R2 logic
✅ Implement tonSigner.SignTx() using tonutils-go signing
✅ Make Signer interface use the same libraries as TON Wallet Gen

Revised Implementation Plan:

// ton_tron_placeholders.go (replace)

import (
    "crypto/ed25519"
    "github.com/xssnick/tonutils-go/address"
    "github.com/xssnick/tonutils-go/ton/wallet"
)

type tonSigner struct{}

func (t *tonSigner) Address(pub PubKey, chain Chain) (string, error) {
    // ✅ Use same logic as TON Wallet Gen v4R2
    publicKey := ed25519.PublicKey(pub)
    rawAddr := address.NewAddress(0, 0, publicKey) 
    
    // Return bounceable form (user-facing)
    return rawAddr.Bounce(true).String(), nil
}

func (t *tonSigner) SignTx(chain Chain, priv PrivKey, payload []byte) ([]byte, error) {
    // ✅ Use tonutils-go for proper TON transaction signing
    privateKey := ed25519.PrivateKey(priv)
    
    // Sign using ed25519
    signature := ed25519.Sign(privateKey, payload)
    return signature, nil
}

Key Insight: We’re not starting from scratch! We’re integrating existing working code.

🚀 RECOMMENDED APPROACH FOR TASK 0.1

Step 1: Understand What’s Working

✅ Read ton_wallet_generator_v4r2.go (lines 33-104)
✅ See how tonutils-go is used
✅ Understand address generation logic

Step 2: Copy the Working Logic

✅ Take address generation from TON Wallet Gen v4R2
✅ Use same library calls
✅ Put into tonSigner.Address()

Step 3: Add Transaction Signing

✅ Use ed25519.Sign() (standard library)
✅ Or use tonutils-go transaction building
✅ Put into tonSigner.SignTx()

Step 4: Test Integration

✅ Generate address with TON Wallet Gen v4R2
✅ Sign transaction with tonSigner
✅ Verify both use same keypair format

📊 DEPENDENCIES STATUS

✅ github.com/xssnick/tonutils-go v1.14.1    Already in go.mod
✅ golang.org/x/crypto v0.39.0                Already in go.mod
❌ github.com/fbsobreira/gotron-sdk           Need to add (Task 0.2)
❌ github.com/ethereum/go-ethereum            Need to add (Task 0.2)

🎯 SUCCESS CRITERIA (Revised)

Task 0.1 Complete When:

✅ tonSigner.Address() generates same addresses as TON Wallet Gen v4R2
✅ tonSigner.SignTx() signs transactions properly
✅ Integration tests pass
✅ Can withdraw TON (end-to-end)

Don’t Reinvent:

❌ Don’t rewrite mnemonic generation
❌ Don’t rewrite v4R2 address logic
❌ Don’t create new TON libraries

Do Integrate:

✅ Use existing tonutils-go functions
✅ Match TON Wallet Gen v4R2 behavior
✅ Keep same address format

📝 NOTES FOR IMPLEMENTATION

Key Files to Reference:

ton_wallet_generator_v4r2.go (lines 33-104) - Working address generation
wallet.service.go (lines 827-873) - How it’s currently used
interfaces.go - Signer interface definition

Libraries Already Available:

github.com/xssnick/tonutils-go/address ✅
github.com/xssnick/tonutils-go/ton/wallet ✅
crypto/ed25519 ✅

Don’t Touch (Working):

TON Wallet Generator v4R2 implementation
Mnemonic encryption/decryption
Database repositories

Do Modify:

ton_tron_placeholders.go - Replace placeholders
Add tests for signing
Integrate with withdrawal flow

🎓 LESSON LEARNED

Before starting ANY task: 1. ✅ Explore what already exists 2. ✅ Find working implementations 3. ✅ Reuse and integrate, don’t rewrite 4. ✅ Understand the disconnect

In this case: - We have working TON wallet generation - We have broken transaction signing - We just need to bridge them!

Next Step: Start Task 0.1 with this understanding.
Time Estimate: 2-3 hours (down from 4-6) because we’re integrating, not building from scratch.