feat(ads): rewarded video (VK) — client-attested credit + daily/hourly caps

The first ads slice: a voluntary rewarded video credits chips. VK Mini App ads
(VKWebAppShowNativeAds) expose only a client-side watch result — no
server-to-server verify — so the credit is client-attested, guarded by a server
daily + hourly cap (config reward_daily_cap / reward_hourly_cap, default 50 / 10).
The caps are both anti-abuse (bounding a forger who skips the ad and calls the
endpoint directly) and an economic conversion lever (limiting free chips so a
player who wants more buys). D29 amended to VK's reality.

Backend: CreditReward (VK-only, order-less, idempotent on a client nonce, floored
by the caps; payout from config rewarded_payout_chips, default 0 = off) + the
wallet.reward edge op returning the updated wallet (reward_chips gates the
"watch for chips" CTA). Additive migration (two config columns).

Client: the ads-network abstraction (lib/ads.ts, VK impl) + the VK bridge
(vkRewardedReady / vkShowRewarded) + the Wallet CTA + i18n. A contour test stub
(VITE_ADS_STUB -> a toast instead of a real ad; prod always real) and a temporary
diagnostic that logs the raw VK data, so we confirm on the contour exactly what
VK returns (harden to signature-verify if it carries one).

Tests: backend integration (credit, nonce idempotency, hourly cap, disabled,
non-VK refusal) + codec unit (reward wire). Docs: PAYMENTS(+ru) §10, D29 amend,
PLAN E6. Bundle: shared budget 30->31 (reward i18n strings).

gateway/Dockerfile

@@ -29,6 +29,9 @@ ARG VITE_VK_APP_ID=
 ARG VITE_VK_ID_REDIRECT_URL=
 ARG VITE_GATEWAY_URL=
 ARG VITE_APP_VERSION=
+# VITE_ADS_STUB=1 substitutes a toast stub for real ads (the test contour only); production leaves it
+# empty so it always shows real ads (a failed real ad must not credit).
+ARG VITE_ADS_STUB=
 ENV VITE_TELEGRAM_BOT_ID=$VITE_TELEGRAM_BOT_ID \
     VITE_TELEGRAM_LINK=$VITE_TELEGRAM_LINK \
     VITE_TELEGRAM_GAME_CHANNEL_NAME=$VITE_TELEGRAM_GAME_CHANNEL_NAME \
@@ -36,7 +39,8 @@ ENV VITE_TELEGRAM_BOT_ID=$VITE_TELEGRAM_BOT_ID \
     VITE_VK_APP_ID=$VITE_VK_APP_ID \
     VITE_VK_ID_REDIRECT_URL=$VITE_VK_ID_REDIRECT_URL \
     VITE_GATEWAY_URL=$VITE_GATEWAY_URL \
-    VITE_APP_VERSION=$VITE_APP_VERSION
+    VITE_APP_VERSION=$VITE_APP_VERSION \
+    VITE_ADS_STUB=$VITE_ADS_STUB
 
 # Install with the lockfile first (the workspace file carries pnpm's build-script
 # approval for esbuild), then build. Committed src/gen/ means no codegen here.

gateway/internal/backendclient/api.go

@@ -369,12 +369,14 @@ type WalletSegmentResp struct {
 }
 
 // WalletResp is the caller's wallet: the context-visible chip segments and the context-applicable
-// benefits (no-ads term end as unix millis / forever flag, and the available hints).
+// benefits (no-ads term end as unix millis / forever flag, and the available hints), plus the
+// rewarded-video payout available in the current context (0 = unavailable — outside VK/unconfigured).
 type WalletResp struct {
 	Segments     []WalletSegmentResp `json:"segments"`
 	AdsForever   bool                `json:"ads_forever"`
 	AdsPaidUntil int64               `json:"ads_paid_until_ms"`
 	Hints        int                 `json:"hints"`
+	RewardChips  int                 `json:"reward_chips"`
 }
 
 // walletBuyBody is the chip-spend request body.
@@ -382,6 +384,21 @@ type walletBuyBody struct {
 	ProductID string `json:"product_id"`
 }
 
+// walletRewardBody is the rewarded-video credit request: the per-view idempotency nonce and the raw
+// VK ad result forwarded for the temporary contour diagnostic.
+type walletRewardBody struct {
+	Nonce string `json:"nonce"`
+	Diag  string `json:"diag"`
+}
+
+// WalletReward credits a watched rewarded video and returns the updated wallet (client-attested + a
+// backend daily cap). A reached cap or unconfigured payout surfaces as an APIError domain code.
+func (c *Client) WalletReward(ctx context.Context, userID, nonce, diag string) (WalletResp, error) {
+	var out WalletResp
+	err := c.do(ctx, http.MethodPost, "/api/v1/user/wallet/reward", userID, "", walletRewardBody{Nonce: nonce, Diag: diag}, &out)
+	return out, err
+}
+
 // Wallet fetches the caller's wallet in their current execution context.
 func (c *Client) Wallet(ctx context.Context, userID string) (WalletResp, error) {
 	var out WalletResp

gateway/internal/transcode/encode.go

@@ -116,6 +116,7 @@ func encodeWallet(w backendclient.WalletResp) []byte {
 	fb.WalletAddAdsForever(b, w.AdsForever)
 	fb.WalletAddAdsPaidUntilMs(b, w.AdsPaidUntil)
 	fb.WalletAddHints(b, int32(w.Hints))
+	fb.WalletAddRewardChips(b, int32(w.RewardChips))
 	b.Finish(fb.WalletEnd(b))
 	return b.FinishedBytes()
 }

gateway/internal/transcode/transcode.go

@@ -56,6 +56,7 @@ const (
 	MsgWalletCatalog        = "wallet.catalog"
 	MsgWalletBuy            = "wallet.buy"
 	MsgWalletOrder          = "wallet.order"
+	MsgWalletReward         = "wallet.reward"
 )
 
 // Request is one decoded Execute call.
@@ -113,6 +114,7 @@ func NewRegistry(backend *backendclient.Client, tg TelegramValidator, opts ...Op
 	r.ops[MsgWalletCatalog] = Op{Handler: walletCatalogHandler(backend), Auth: true}
 	r.ops[MsgWalletBuy] = Op{Handler: walletBuyHandler(backend), Auth: true}
 	r.ops[MsgWalletOrder] = Op{Handler: walletOrderHandler(backend, nil), Auth: true}
+	r.ops[MsgWalletReward] = Op{Handler: walletRewardHandler(backend), Auth: true}
 	r.ops[MsgBlockStatus] = Op{Handler: blockStatusHandler(backend), Auth: true}
 	r.ops[MsgGameSubmitPlay] = Op{Handler: submitPlayHandler(backend), Auth: true}
 	r.ops[MsgGameState] = Op{Handler: gameStateHandler(backend), Auth: true}
@@ -379,6 +381,19 @@ func walletOrderHandler(backend *backendclient.Client, minter InvoiceMinter) Han
 	}
 }
 
+// walletRewardHandler credits a watched rewarded video and returns the updated wallet. The nonce is
+// the client's per-view idempotency key; diag carries the raw VK ad result for the contour diagnostic.
+func walletRewardHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsWalletRewardRequest(req.Payload, 0)
+		w, err := backend.WalletReward(ctx, req.UserID, string(in.Nonce()), string(in.Diag()))
+		if err != nil {
+			return nil, err
+		}
+		return encodeWallet(w), nil
+	}
+}
+
 func blockStatusHandler(backend *backendclient.Client) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		bs, err := backend.BlockStatus(ctx, req.UserID)