feat(pay): pangolin-pay 钱包派生模块(#34/34A · 加密货币交易引擎 Phase B.2)

新建独立 Go module pay/(pangolin-pay:独立 VPS 跑,与控制面分开、隔离 crypto 依赖)。 wallet 包: - AddressFromAccountXpub(xpub, change, index):watch-only 从账户 xpub 派生 TRON 地址 (Keccak-256 legacy → 后20字节 → 0x41 → base58check),watcher 用,不碰私钥。 - seed.go(离线专用):助记词→account xpub / 地址私钥(hex),给 Phase A 导 xpub、Phase D 归集签名。 - 测试:①派生一致性——xpub 路径与私钥路径逐个相等(证明每个收款地址对得上签名私钥); ②金标准向量锁定实现防回归。⚠️ 金标准需按 A.4 用 Ian Coleman 交叉核对一次。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-09 02:50:24 +08:00
parent 9a8fec2e9c
commit 4393edf1d7
5 changed files with 314 additions and 0 deletions
@@ -0,0 +1,78 @@
+// Package wallet derives TRON (TRC20) receiving addresses from a BIP32 account
+// extended public key (xpub) — watch-only, no private keys involved. The
+// pangolin-pay watcher uses AddressFromAccountXpub to assign a unique receiving
+// address per order (m/44'/195'/0'/0/i). Private-key material (seed.go) is for
+// OFFLINE use only (sweep signing / vector generation), never on the hot service.
+package wallet
+
+import (
+	"crypto/sha256"
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcutil/base58"
+	"github.com/btcsuite/btcd/btcutil/hdkeychain"
+	"golang.org/x/crypto/sha3"
+)
+
+// tronAddrPrefix is the TRON mainnet address version byte (0x41). It is prepended
+// to the 20-byte address body before Base58Check encoding, yielding the familiar
+// "T..." addresses.
+const tronAddrPrefix = 0x41
+
+// AddressFromAccountXpub derives the TRON address at m/…/<change>/<index> from an
+// account-level extended public key (e.g. the xpub of m/44'/195'/0'). It is
+// watch-only: an xpub can derive child addresses/public keys but never private
+// keys, so this is safe to run on an internet-facing service.
+//
+// change is 0 for the external (receiving) chain; index is the per-order address
+// index. Both are non-hardened, which is exactly why the account-level xpub can
+// derive them.
+func AddressFromAccountXpub(xpub string, change, index uint32) (string, error) {
+	acct, err := hdkeychain.NewKeyFromString(xpub)
+	if err != nil {
+		return "", fmt.Errorf("wallet: parse xpub: %w", err)
+	}
+	if acct.IsPrivate() {
+		return "", fmt.Errorf("wallet: expected an xpub (public extended key), got a private one")
+	}
+	chainKey, err := acct.Derive(change)
+	if err != nil {
+		return "", fmt.Errorf("wallet: derive change %d: %w", change, err)
+	}
+	addrKey, err := chainKey.Derive(index)
+	if err != nil {
+		return "", fmt.Errorf("wallet: derive index %d: %w", index, err)
+	}
+	pub, err := addrKey.ECPubKey()
+	if err != nil {
+		return "", fmt.Errorf("wallet: ec pubkey: %w", err)
+	}
+	return PubKeyToTronAddress(pub.SerializeUncompressed()), nil
+}
+
+// PubKeyToTronAddress converts a 65-byte uncompressed secp256k1 public key
+// (0x04 || X || Y) to a TRON Base58Check address:
+//
+//	body     = 0x41 || keccak256(X||Y)[12:]   // last 20 bytes of the Keccak hash
+//	address  = Base58( body || dsha256(body)[:4] )
+//
+// Note: TRON/Ethereum use *legacy* Keccak-256 (not the finalized SHA3-256).
+func PubKeyToTronAddress(uncompressed []byte) string {
+	h := sha3.NewLegacyKeccak256()
+	h.Write(uncompressed[1:]) // drop the 0x04 prefix; hash the 64-byte X||Y
+	sum := h.Sum(nil)
+	body := append([]byte{tronAddrPrefix}, sum[12:]...) // 0x41 + last 20 bytes
+	return base58CheckEncode(body)
+}
+
+// base58CheckEncode appends a 4-byte double-SHA256 checksum and Base58-encodes.
+// (TRON's version byte 0x41 is already inside input, so this is a plain
+// checksum-append, not btcutil's version-byte CheckEncode.)
+func base58CheckEncode(input []byte) string {
+	first := sha256.Sum256(input)
+	second := sha256.Sum256(first[:])
+	full := make([]byte, 0, len(input)+4)
+	full = append(full, input...)
+	full = append(full, second[:4]...)
+	return base58.Encode(full)
+}
@@ -0,0 +1,99 @@
+package wallet
+
+import (
+	"strings"
+	"testing"
+)
+
+// testMnemonic is the canonical all-zero-entropy BIP39 test vector. The derived
+// TRON addresses logged by TestAccountXpubDeriveConsistency must match
+// iancoleman.io/bip39 (Coin = TRX, BIP44) — that manual comparison is Phase A.4
+// of the crypto-tx-engine plan (guards against a derivation mismatch that would
+// silently send funds to addresses we don't control).
+const testMnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+// TestAccountXpubDeriveConsistency proves the watcher's watch-only path
+// (xpub -> address) yields exactly the same address as the offline private path
+// (seed -> privkey -> pubkey -> address) for each index. That equality is what
+// guarantees every receiving address the watcher hands out is spendable by the
+// key we hold in cold storage.
+func TestAccountXpubDeriveConsistency(t *testing.T) {
+	xpub, err := AccountXpubFromMnemonic(testMnemonic, "", 0)
+	if err != nil {
+		t.Fatalf("account xpub: %v", err)
+	}
+	t.Logf("account xpub (m/44'/195'/0'): %s", xpub)
+
+	acct, err := AccountKeyFromMnemonic(testMnemonic, "", 0)
+	if err != nil {
+		t.Fatalf("account key: %v", err)
+	}
+
+	for i := uint32(0); i < 5; i++ {
+		viaXpub, err := AddressFromAccountXpub(xpub, 0, i) // what the watcher does
+		if err != nil {
+			t.Fatalf("via xpub [%d]: %v", i, err)
+		}
+
+		ck, err := acct.Derive(0)
+		if err != nil {
+			t.Fatalf("derive change: %v", err)
+		}
+		ak, err := ck.Derive(i)
+		if err != nil {
+			t.Fatalf("derive index %d: %v", i, err)
+		}
+		pub, err := ak.ECPubKey()
+		if err != nil {
+			t.Fatalf("ec pubkey: %v", err)
+		}
+		viaPriv := PubKeyToTronAddress(pub.SerializeUncompressed())
+
+		if viaXpub != viaPriv {
+			t.Fatalf("index %d: xpub-derived %q != priv-derived %q", i, viaXpub, viaPriv)
+		}
+		if !strings.HasPrefix(viaXpub, "T") || len(viaXpub) != 34 {
+			t.Fatalf("index %d: not a valid TRON address: %q", i, viaXpub)
+		}
+		t.Logf("m/44'/195'/0'/0/%d -> %s", i, viaXpub)
+	}
+}
+
+// TestKnownVector locks the derivation to a golden result (filled from the run of
+// TestAccountXpubDeriveConsistency, then confirmed against iancoleman.io — A.4).
+// If this ever changes, the derivation implementation regressed.
+func TestKnownVector(t *testing.T) {
+	if len(goldenAddrs) == 0 {
+		t.Skip("golden vector not yet baked — run TestAccountXpubDeriveConsistency, confirm vs Ian Coleman, then fill goldenAddrs")
+	}
+	xpub, err := AccountXpubFromMnemonic(testMnemonic, "", 0)
+	if err != nil {
+		t.Fatalf("xpub: %v", err)
+	}
+	if goldenXpub != "" && xpub != goldenXpub {
+		t.Fatalf("account xpub changed:\n got  %s\n want %s", xpub, goldenXpub)
+	}
+	for i, want := range goldenAddrs {
+		got, err := AddressFromAccountXpub(xpub, 0, uint32(i))
+		if err != nil {
+			t.Fatalf("addr[%d]: %v", i, err)
+		}
+		if got != want {
+			t.Fatalf("addr[%d]: got %s want %s", i, got, want)
+		}
+	}
+}
+
+// Golden vector for the "abandon…about" test mnemonic, Coin=TRX, m/44'/195'/0'.
+// Locks the derivation against regression. ⚠️ MUST be confirmed once against
+// iancoleman.io/bip39 (Phase A.4) — self-consistency (TestAccountXpubDeriveConsistency)
+// proves the xpub and private paths agree, but only an independent tool proves
+// both aren't wrong the same way. If Ian Coleman disagrees, the impl has a bug.
+var (
+	goldenXpub  = "xpub6D1AabNHCupeiLM65ZR9UStMhJ1vCpyV4XbZdyhMZBiJXALQtmn9p42VTQckoHVn8WNqS7dqnJokZHAHcHGoaQgmv8D45oNUKx6DZMNZBCd"
+	goldenAddrs = []string{
+		"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH", // m/44'/195'/0'/0/0
+		"TSeJkUh4Qv67VNFwY8LaAxERygNdy6NQZK", // m/44'/195'/0'/0/1
+		"TYJPRrdB5APNeRs4R7fYZSwW3TcrTKw2gx", // m/44'/195'/0'/0/2
+	}
+)
@@ -0,0 +1,86 @@
+package wallet
+
+import (
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcutil/hdkeychain"
+	"github.com/btcsuite/btcd/chaincfg"
+	bip39 "github.com/tyler-smith/go-bip39"
+)
+
+// ⚠️ OFFLINE ONLY. Everything in this file touches the BIP39 seed / private keys.
+// It exists for (a) generating the account xpub to hand to the watcher, and
+// (b) deriving per-address private keys for offline sweep signing (Phase D).
+// It must NEVER be linked into or run on the internet-facing pangolin-pay
+// watcher — the hot service only ever handles the account xpub (see derive.go).
+
+const (
+	purposeBIP44 = 44
+	coinTypeTRON = 195
+	// hardenedOffset marks a derivation index as hardened (requires the private
+	// key). BIP44's first three levels (purpose'/coin'/account') are hardened.
+	hardenedOffset = hdkeychain.HardenedKeyStart // 0x80000000
+)
+
+// AccountKeyFromMnemonic derives the account-level extended *private* key at
+// m/44'/195'/<account>' from a BIP39 mnemonic (+ optional passphrase).
+// OFFLINE ONLY.
+func AccountKeyFromMnemonic(mnemonic, passphrase string, account uint32) (*hdkeychain.ExtendedKey, error) {
+	if !bip39.IsMnemonicValid(mnemonic) {
+		return nil, fmt.Errorf("wallet: invalid BIP39 mnemonic (checksum/wordlist)")
+	}
+	seed := bip39.NewSeed(mnemonic, passphrase)
+	master, err := hdkeychain.NewMaster(seed, &chaincfg.MainNetParams)
+	if err != nil {
+		return nil, fmt.Errorf("wallet: master key: %w", err)
+	}
+	for _, step := range []uint32{
+		hardenedOffset + purposeBIP44,
+		hardenedOffset + coinTypeTRON,
+		hardenedOffset + account,
+	} {
+		master, err = master.Derive(step)
+		if err != nil {
+			return nil, fmt.Errorf("wallet: derive account path: %w", err)
+		}
+	}
+	return master, nil
+}
+
+// AccountXpubFromMnemonic returns the account-level xpub string to hand to the
+// watcher. OFFLINE ONLY — run this once on the air-gapped machine, copy only the
+// returned xpub to the hot service.
+func AccountXpubFromMnemonic(mnemonic, passphrase string, account uint32) (string, error) {
+	k, err := AccountKeyFromMnemonic(mnemonic, passphrase, account)
+	if err != nil {
+		return "", err
+	}
+	pub, err := k.Neuter() // strip the private key -> xpub
+	if err != nil {
+		return "", fmt.Errorf("wallet: neuter: %w", err)
+	}
+	return pub.String(), nil
+}
+
+// PrivKeyHexFromMnemonic derives the raw secp256k1 private key (hex) for the
+// address at m/44'/195'/<account>'/<change>/<index>, for offline sweep signing.
+// OFFLINE ONLY.
+func PrivKeyHexFromMnemonic(mnemonic, passphrase string, account, change, index uint32) (string, error) {
+	acct, err := AccountKeyFromMnemonic(mnemonic, passphrase, account)
+	if err != nil {
+		return "", err
+	}
+	chainKey, err := acct.Derive(change)
+	if err != nil {
+		return "", fmt.Errorf("wallet: derive change: %w", err)
+	}
+	addrKey, err := chainKey.Derive(index)
+	if err != nil {
+		return "", fmt.Errorf("wallet: derive index: %w", err)
+	}
+	priv, err := addrKey.ECPrivKey()
+	if err != nil {
+		return "", fmt.Errorf("wallet: ec privkey: %w", err)
+	}
+	return fmt.Sprintf("%x", priv.Serialize()), nil
+}