e2e: add USDC balance verification to multicast settlement QA test (#3456)

## Summary of Changes
- Adds `GetWalletPubkey` QA agent RPC to read a Solana keypair file and
return the base58-encoded public key
- Adds `GetUSDCBalance` to the QA client, deriving the ATA from the
wallet pubkey and querying the Solana RPC
- Adds `GetEffectiveSeatPrice` to the QA client, which respects per-seat
price overrides vs. epoch price
- Extends `TestQA_MulticastSettlement` with balance snapshot/assertion
subtests before pay, after pay, and after withdrawal

## Diff Breakdown
| Category    | Files | Lines (+/-) | Net  |
|-------------|-------|-------------|------|
| Core logic  |     3 | +172 / -6   | +166 |
| Scaffolding |     3 | +131 / -22  | +109 |
| Tests       |     1 | +54 / -11   |  +43 |

Mostly new test infrastructure (client helpers + proto RPC) to support
richer settlement assertions.

<details>
<summary>Key files (click to expand)</summary>

- `e2e/internal/qa/client_settlement.go` — added
`GetEffectiveSeatPrice`, `GetWalletPubkey`, and `GetUSDCBalance` client
methods
- `e2e/qa_multicast_settlement_test.go` — added
`record_balance_before_pay`, `validate_balance_after_pay`,
`query_effective_seat_price`, and `validate_balance_after_withdraw`
subtests
- `e2e/internal/rpc/agent.go` — implemented `GetWalletPubkey` gRPC
handler (reads keypair JSON, returns base58 pubkey)
- `e2e/proto/qa/agent.proto` — added `GetWalletPubkey` RPC and
request/response messages

</details>

## Testing Verification
- Ran `TestQA_MulticastSettlement` against testnet and mainnet QA
environments; all subtests passed including the new balance assertions

Author: snormore

config/constants.go

@@ -16,7 +16,7 @@ const (
 	MainnetRevenueDistributionProgramID = "dzrevZC94tBLwuHw1dyynZxaXTWyp7yocsinyEVPtt4"
 	MainnetGeolocationProgramID         = "8H7nS6eZiuf7rGQtz3PPz2q9m4eJRL37PPM678KHnspG"
 	MainnetShredSubscriptionProgramID   = "dzshrr3yL57SB13sJPYHYo3TV8Bo1i1FxkyrZr3bKNE"
-	MainnetUSDCMint                     = "" // CLI defaults to real USDC on mainnet
+	MainnetUSDCMint                     = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
 
 	// Testnet constants.
 	TestnetLedgerPublicRPCURL            = "https://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16"

e2e/internal/qa/client_settlement.go

@@ -2,10 +2,15 @@ package qa
 
 import (
 	"context"
+	"encoding/binary"
 	"fmt"
 	"math"
+	"strconv"
 
+	"github.com/gagliardetto/solana-go"
+	"github.com/gagliardetto/solana-go/rpc"
 	pb "github.com/malbeclabs/doublezero/e2e/proto/qa/gen/pb-go"
+	shreds "github.com/malbeclabs/doublezero/sdk/shreds/go"
 	"google.golang.org/protobuf/types/known/emptypb"
 )
 
@@ -120,3 +125,88 @@ func (c *Client) FeedSeatWithdraw(ctx context.Context, devicePubkey string) erro
 	c.log.Debug("Seat withdrawal successful", "host", c.Host, "device", devicePubkey)
 	return nil
 }
+
+// GetEffectiveSeatPrice returns the effective per-epoch price for the client's
+// seat on the given device, in raw USDC (6 decimals). If the client seat has a
+// price override, the override is returned; otherwise the epoch price (in whole
+// dollars, converted to micro-USDC) is used.
+func (c *Client) GetEffectiveSeatPrice(ctx context.Context, devicePubkey string, epochPrice uint64) (uint64, error) {
+	deviceKey, err := solana.PublicKeyFromBase58(devicePubkey)
+	if err != nil {
+		return 0, fmt.Errorf("failed to parse device pubkey %q: %w", devicePubkey, err)
+	}
+
+	programID, err := solana.PublicKeyFromBase58(c.ShredSubscriptionProgramID)
+	if err != nil {
+		return 0, fmt.Errorf("failed to parse shred subscription program ID %q: %w", c.ShredSubscriptionProgramID, err)
+	}
+
+	clientIPBits := binary.BigEndian.Uint32(c.publicIP.To4())
+	shredsClient := shreds.New(shreds.NewRPCClient(c.SolanaRPCURL), programID)
+	seat, err := shredsClient.FetchClientSeat(ctx, deviceKey, clientIPBits)
+	if err != nil {
+		return 0, fmt.Errorf("failed to fetch client seat on host %s: %w", c.Host, err)
+	}
+
+	if seat.HasPriceOverride() {
+		price := uint64(seat.OverrideUSDCPriceDollars) * 1_000_000
+		c.log.Debug("Seat has price override", "host", c.Host, "override_dollars", seat.OverrideUSDCPriceDollars, "price_usdc", price)
+		return price, nil
+	}
+
+	price := epochPrice * 1_000_000
+	c.log.Debug("Seat using epoch price", "host", c.Host, "epoch_price_dollars", epochPrice, "price_usdc", price)
+	return price, nil
+}
+
+// GetWalletPubkey calls the GetWalletPubkey RPC to read the keypair file on the
+// remote host and return the base58-encoded public key.
+func (c *Client) GetWalletPubkey(ctx context.Context) (solana.PublicKey, error) {
+	resp, err := c.grpcClient.GetWalletPubkey(ctx, &pb.GetWalletPubkeyRequest{
+		Keypair: c.Keypair,
+	})
+	if err != nil {
+		return solana.PublicKey{}, fmt.Errorf("failed to get wallet pubkey on host %s: %w", c.Host, err)
+	}
+	pubkey, err := solana.PublicKeyFromBase58(resp.GetPubkey())
+	if err != nil {
+		return solana.PublicKey{}, fmt.Errorf("failed to parse wallet pubkey %q: %w", resp.GetPubkey(), err)
+	}
+	c.log.Debug("Wallet pubkey retrieved", "host", c.Host, "pubkey", pubkey)
+	return pubkey, nil
+}
+
+// GetUSDCBalance queries the USDC token balance for the client's wallet.
+// It derives the associated token account from the wallet pubkey and USDC mint,
+// then queries the balance via the Solana RPC (which points to the DZ ledger
+// on testnet/devnet and Solana proper on mainnet).
+func (c *Client) GetUSDCBalance(ctx context.Context) (uint64, error) {
+	ownerPubkey, err := c.GetWalletPubkey(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get wallet pubkey on host %s: %w", c.Host, err)
+	}
+
+	usdcMint, err := solana.PublicKeyFromBase58(c.USDCMint)
+	if err != nil {
+		return 0, fmt.Errorf("failed to parse USDC mint %q: %w", c.USDCMint, err)
+	}
+
+	ata, _, err := solana.FindAssociatedTokenAddress(ownerPubkey, usdcMint)
+	if err != nil {
+		return 0, fmt.Errorf("failed to derive ATA for owner %s and mint %s: %w", ownerPubkey, usdcMint, err)
+	}
+
+	solanaClient := rpc.New(c.SolanaRPCURL)
+	result, err := solanaClient.GetTokenAccountBalance(ctx, ata, rpc.CommitmentConfirmed)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get token account balance for ATA %s on host %s: %w", ata, c.Host, err)
+	}
+
+	balance, err := strconv.ParseUint(result.Value.Amount, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("failed to parse balance %q: %w", result.Value.Amount, err)
+	}
+
+	c.log.Debug("USDC balance retrieved", "host", c.Host, "owner", ownerPubkey, "ata", ata, "balance", balance)
+	return balance, nil
+}

e2e/internal/rpc/agent.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/malbeclabs/doublezero/e2e/internal/netutil"
 	pb "github.com/malbeclabs/doublezero/e2e/proto/qa/gen/pb-go"
+	"github.com/mr-tron/base58"
 	probing "github.com/prometheus-community/pro-bing"
 	"golang.org/x/net/ipv4"
 	"golang.org/x/sys/unix"
@@ -503,6 +504,33 @@ func (q *QAAgent) FeedSeatWithdraw(ctx context.Context, req *pb.FeedSeatWithdraw
 	return res, nil
 }
 
+// GetWalletPubkey reads a Solana keypair JSON file and returns the base58-encoded
+// public key. The keypair format is a JSON array of 64 bytes: the first 32 are the
+// private key, the last 32 are the public key.
+func (q *QAAgent) GetWalletPubkey(_ context.Context, req *pb.GetWalletPubkeyRequest) (*pb.GetWalletPubkeyResponse, error) {
+	keypairPath := os.ExpandEnv(req.GetKeypair())
+	if keypairPath == "" {
+		return nil, fmt.Errorf("keypair path is required")
+	}
+
+	data, err := os.ReadFile(keypairPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read keypair file %s: %w", keypairPath, err)
+	}
+
+	var keyBytes []byte
+	if err := json.Unmarshal(data, &keyBytes); err != nil {
+		return nil, fmt.Errorf("failed to parse keypair JSON from %s: %w", keypairPath, err)
+	}
+	if len(keyBytes) != 64 {
+		return nil, fmt.Errorf("invalid keypair length %d (expected 64) in %s", len(keyBytes), keypairPath)
+	}
+
+	pubkey := base58.Encode(keyBytes[32:])
+	q.log.Debug("Wallet pubkey retrieved", "keypair", keypairPath, "pubkey", pubkey)
+	return &pb.GetWalletPubkeyResponse{Pubkey: pubkey}, nil
+}
+
 type StatusResponse struct {
 	Response struct {
 		TunnelName       string `json:"tunnel_name"`

e2e/proto/qa/agent.proto

@@ -28,6 +28,7 @@ service QAAgentService {
   rpc FeedSeatPrice(FeedSeatPriceRequest) returns (FeedSeatPriceResponse);
   rpc FeedSeatPay(FeedSeatPayRequest) returns (Result);
   rpc FeedSeatWithdraw(FeedSeatWithdrawRequest) returns (Result);
+  rpc GetWalletPubkey(GetWalletPubkeyRequest) returns (GetWalletPubkeyResponse);
 }
 
 message ConnectUnicastRequest {
@@ -255,3 +256,11 @@ message DevicePrice {
 message FeedSeatPriceResponse {
   repeated DevicePrice prices = 1;
 }
+
+message GetWalletPubkeyRequest {
+  string keypair = 1;
+}
+
+message GetWalletPubkeyResponse {
+  string pubkey = 1;
+}