feat(payments): Telegram Stars payment rail

Accept real money via Telegram Stars (XTR) — the third intake rail
alongside Robokassa (direct) and VK Votes.

Only the bot reaches Telegram, so the rail funnels through the reverse
mTLS bot-link:
- the gateway mints the invoice on a CreateInvoice command (the bot
  calls createInvoiceLink, XTR; the link goes to WebApp.openInvoice);
- the bot gates each pre_checkout_query via a ValidatePreCheckout unary
  (the order must exist, be still creditable and not already paid — the
  reusable-invoice double-pay guard; the decline reason is localised to
  the order account's language);
- a completed successful_payment is queued in a durable pure-Go SQLite
  outbox and forwarded via a ForwardPayment unary, credited once
  (idempotent on telegram_payment_charge_id, honours an expired order),
  re-driven on restart and every 30s.

The rail is wired by TELEGRAM_STARS_OUTBOX_DIR (default /data) but stays
inert until a chip pack carries an XTR price, so seeding a Stars price in
the admin is the go-live.

Tests: backend integration (order->forward->credit once, duplicate,
pre_checkout gate) + bot outbox unit (idempotent, restart re-drive) +
executor createInvoice. Docs: PAYMENTS(+ru) §9, ARCHITECTURE, the
platform/telegram README, PLAN.

pkg/proto/botlink/v1/botlink.pb.go

@@ -225,6 +225,7 @@ type Command struct {
 	//	*Command_SendToUser
 	//	*Command_SendToChannel
 	//	*Command_ChatGate
+	//	*Command_CreateInvoice
 	Payload       isCommand_Payload `protobuf_oneof:"payload"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
@@ -310,6 +311,15 @@ func (x *Command) GetChatGate() *ChatGateCommand {
 	return nil
 }
 
+func (x *Command) GetCreateInvoice() *CreateInvoiceCommand {
+	if x != nil {
+		if x, ok := x.Payload.(*Command_CreateInvoice); ok {
+			return x.CreateInvoice
+		}
+	}
+	return nil
+}
+
 type isCommand_Payload interface {
 	isCommand_Payload()
 }
@@ -330,6 +340,10 @@ type Command_ChatGate struct {
 	ChatGate *ChatGateCommand `protobuf:"bytes,5,opt,name=chat_gate,json=chatGate,proto3,oneof"`
 }
 
+type Command_CreateInvoice struct {
+	CreateInvoice *CreateInvoiceCommand `protobuf:"bytes,6,opt,name=create_invoice,json=createInvoice,proto3,oneof"`
+}
+
 func (*Command_Notify) isCommand_Payload() {}
 
 func (*Command_SendToUser) isCommand_Payload() {}
@@ -338,15 +352,20 @@ func (*Command_SendToChannel) isCommand_Payload() {}
 
 func (*Command_ChatGate) isCommand_Payload() {}
 
+func (*Command_CreateInvoice) isCommand_Payload() {}
+
 // Ack reports the outcome of the Command with command_id. delivered mirrors the
 // connector delivery semantics (false when the kind is not rendered out-of-app, the
 // user never started the bot, or no channel is configured); error carries an
-// unexpected transport/render failure, distinct from a clean not-delivered.
+// unexpected transport/render failure, distinct from a clean not-delivered. result
+// carries a command's return value when it has one (the created invoice link for a
+// create_invoice command); it is empty otherwise.
 type Ack struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	CommandId     string                 `protobuf:"bytes,1,opt,name=command_id,json=commandId,proto3" json:"command_id,omitempty"`
 	Delivered     bool                   `protobuf:"varint,2,opt,name=delivered,proto3" json:"delivered,omitempty"`
 	Error         string                 `protobuf:"bytes,3,opt,name=error,proto3" json:"error,omitempty"`
+	Result        string                 `protobuf:"bytes,4,opt,name=result,proto3" json:"result,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
 }
@@ -402,6 +421,13 @@ func (x *Ack) GetError() string {
 	return ""
 }
 
+func (x *Ack) GetResult() string {
+	if x != nil {
+		return x.Result
+	}
+	return ""
+}
+
 // ChatGateCommand sets a Telegram user's write access in the moderated discussion
 // chat. external_id is the user's Telegram identity (as in the backend identities
 // table); allow grants the right to write when true and revokes it when false. The
@@ -562,6 +588,314 @@ func (x *ChatEligibilityResponse) GetEligible() bool {
 	return false
 }
 
+// CreateInvoiceCommand asks the bot to mint a Telegram Stars invoice link for a
+// pending order (createInvoiceLink in XTR). payload is the order id, which Telegram
+// echoes back in the pre_checkout_query and the successful_payment; amount is the
+// price in whole stars; title and description are shown on the invoice. The bot
+// returns the link in its Ack result.
+type CreateInvoiceCommand struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Title         string                 `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"`
+	Description   string                 `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
+	Payload       string                 `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
+	Amount        int64                  `protobuf:"varint,4,opt,name=amount,proto3" json:"amount,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CreateInvoiceCommand) Reset() {
+	*x = CreateInvoiceCommand{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CreateInvoiceCommand) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CreateInvoiceCommand) ProtoMessage() {}
+
+func (x *CreateInvoiceCommand) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CreateInvoiceCommand.ProtoReflect.Descriptor instead.
+func (*CreateInvoiceCommand) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{8}
+}
+
+func (x *CreateInvoiceCommand) GetTitle() string {
+	if x != nil {
+		return x.Title
+	}
+	return ""
+}
+
+func (x *CreateInvoiceCommand) GetDescription() string {
+	if x != nil {
+		return x.Description
+	}
+	return ""
+}
+
+func (x *CreateInvoiceCommand) GetPayload() string {
+	if x != nil {
+		return x.Payload
+	}
+	return ""
+}
+
+func (x *CreateInvoiceCommand) GetAmount() int64 {
+	if x != nil {
+		return x.Amount
+	}
+	return 0
+}
+
+// PreCheckoutRequest asks whether a Stars pre_checkout_query for order_id at amount
+// (whole stars) in currency may be approved before the charge.
+type PreCheckoutRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	OrderId       string                 `protobuf:"bytes,1,opt,name=order_id,json=orderId,proto3" json:"order_id,omitempty"`
+	Amount        int64                  `protobuf:"varint,2,opt,name=amount,proto3" json:"amount,omitempty"`
+	Currency      string                 `protobuf:"bytes,3,opt,name=currency,proto3" json:"currency,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *PreCheckoutRequest) Reset() {
+	*x = PreCheckoutRequest{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *PreCheckoutRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PreCheckoutRequest) ProtoMessage() {}
+
+func (x *PreCheckoutRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PreCheckoutRequest.ProtoReflect.Descriptor instead.
+func (*PreCheckoutRequest) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{9}
+}
+
+func (x *PreCheckoutRequest) GetOrderId() string {
+	if x != nil {
+		return x.OrderId
+	}
+	return ""
+}
+
+func (x *PreCheckoutRequest) GetAmount() int64 {
+	if x != nil {
+		return x.Amount
+	}
+	return 0
+}
+
+func (x *PreCheckoutRequest) GetCurrency() string {
+	if x != nil {
+		return x.Currency
+	}
+	return ""
+}
+
+// PreCheckoutResponse is the approval answer. ok approves the charge; reason carries a
+// short user-facing decline message when ok is false.
+type PreCheckoutResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Ok            bool                   `protobuf:"varint,1,opt,name=ok,proto3" json:"ok,omitempty"`
+	Reason        string                 `protobuf:"bytes,2,opt,name=reason,proto3" json:"reason,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *PreCheckoutResponse) Reset() {
+	*x = PreCheckoutResponse{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *PreCheckoutResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PreCheckoutResponse) ProtoMessage() {}
+
+func (x *PreCheckoutResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PreCheckoutResponse.ProtoReflect.Descriptor instead.
+func (*PreCheckoutResponse) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{10}
+}
+
+func (x *PreCheckoutResponse) GetOk() bool {
+	if x != nil {
+		return x.Ok
+	}
+	return false
+}
+
+func (x *PreCheckoutResponse) GetReason() string {
+	if x != nil {
+		return x.Reason
+	}
+	return ""
+}
+
+// ForwardPaymentRequest carries a completed Stars payment: order_id from the invoice
+// payload, the Telegram charge id (the idempotency key), the amount in whole stars,
+// and the payer's Telegram user id.
+type ForwardPaymentRequest struct {
+	state                   protoimpl.MessageState `protogen:"open.v1"`
+	OrderId                 string                 `protobuf:"bytes,1,opt,name=order_id,json=orderId,proto3" json:"order_id,omitempty"`
+	TelegramPaymentChargeId string                 `protobuf:"bytes,2,opt,name=telegram_payment_charge_id,json=telegramPaymentChargeId,proto3" json:"telegram_payment_charge_id,omitempty"`
+	Amount                  int64                  `protobuf:"varint,3,opt,name=amount,proto3" json:"amount,omitempty"`
+	TelegramUserId          int64                  `protobuf:"varint,4,opt,name=telegram_user_id,json=telegramUserId,proto3" json:"telegram_user_id,omitempty"`
+	unknownFields           protoimpl.UnknownFields
+	sizeCache               protoimpl.SizeCache
+}
+
+func (x *ForwardPaymentRequest) Reset() {
+	*x = ForwardPaymentRequest{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ForwardPaymentRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ForwardPaymentRequest) ProtoMessage() {}
+
+func (x *ForwardPaymentRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ForwardPaymentRequest.ProtoReflect.Descriptor instead.
+func (*ForwardPaymentRequest) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{11}
+}
+
+func (x *ForwardPaymentRequest) GetOrderId() string {
+	if x != nil {
+		return x.OrderId
+	}
+	return ""
+}
+
+func (x *ForwardPaymentRequest) GetTelegramPaymentChargeId() string {
+	if x != nil {
+		return x.TelegramPaymentChargeId
+	}
+	return ""
+}
+
+func (x *ForwardPaymentRequest) GetAmount() int64 {
+	if x != nil {
+		return x.Amount
+	}
+	return 0
+}
+
+func (x *ForwardPaymentRequest) GetTelegramUserId() int64 {
+	if x != nil {
+		return x.TelegramUserId
+	}
+	return 0
+}
+
+// ForwardPaymentResponse reports the durable outcome. credited is true when the order
+// was credited (or already had been); false means the payment was recorded but could
+// not be matched to a creditable order (an operator follows up). Either way the bot
+// may forget the outbox row — only a transport error triggers a retry.
+type ForwardPaymentResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Credited      bool                   `protobuf:"varint,1,opt,name=credited,proto3" json:"credited,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ForwardPaymentResponse) Reset() {
+	*x = ForwardPaymentResponse{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ForwardPaymentResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ForwardPaymentResponse) ProtoMessage() {}
+
+func (x *ForwardPaymentResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ForwardPaymentResponse.ProtoReflect.Descriptor instead.
+func (*ForwardPaymentResponse) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *ForwardPaymentResponse) GetCredited() bool {
+	if x != nil {
+		return x.Credited
+	}
+	return false
+}
+
 var File_botlink_v1_botlink_proto protoreflect.FileDescriptor
 
 const file_botlink_v1_botlink_proto_rawDesc = "" +
@@ -576,7 +910,7 @@ const file_botlink_v1_botlink_proto_rawDesc = "" +
 	"\x05Hello\x12\x1f\n" +
 	"\vinstance_id\x18\x01 \x01(\tR\n" +
 	"instanceId\x12!\n" +
-	"\fowns_updates\x18\x02 \x01(\bR\vownsUpdates\"\xde\x02\n" +
+	"\fowns_updates\x18\x02 \x01(\bR\vownsUpdates\"\xb2\x03\n" +
 	"\aCommand\x12\x1d\n" +
 	"\n" +
 	"command_id\x18\x01 \x01(\tR\tcommandId\x12=\n" +
@@ -584,13 +918,15 @@ const file_botlink_v1_botlink_proto_rawDesc = "" +
 	"\fsend_to_user\x18\x03 \x01(\v2'.scrabble.telegram.v1.SendToUserRequestH\x00R\n" +
 	"sendToUser\x12X\n" +
 	"\x0fsend_to_channel\x18\x04 \x01(\v2..scrabble.telegram.v1.SendToGameChannelRequestH\x00R\rsendToChannel\x12C\n" +
-	"\tchat_gate\x18\x05 \x01(\v2$.scrabble.botlink.v1.ChatGateCommandH\x00R\bchatGateB\t\n" +
-	"\apayload\"X\n" +
+	"\tchat_gate\x18\x05 \x01(\v2$.scrabble.botlink.v1.ChatGateCommandH\x00R\bchatGate\x12R\n" +
+	"\x0ecreate_invoice\x18\x06 \x01(\v2).scrabble.botlink.v1.CreateInvoiceCommandH\x00R\rcreateInvoiceB\t\n" +
+	"\apayload\"p\n" +
 	"\x03Ack\x12\x1d\n" +
 	"\n" +
 	"command_id\x18\x01 \x01(\tR\tcommandId\x12\x1c\n" +
 	"\tdelivered\x18\x02 \x01(\bR\tdelivered\x12\x14\n" +
-	"\x05error\x18\x03 \x01(\tR\x05error\"H\n" +
+	"\x05error\x18\x03 \x01(\tR\x05error\x12\x16\n" +
+	"\x06result\x18\x04 \x01(\tR\x06result\"H\n" +
 	"\x0fChatGateCommand\x12\x1f\n" +
 	"\vexternal_id\x18\x01 \x01(\tR\n" +
 	"externalId\x12\x14\n" +
@@ -602,10 +938,31 @@ const file_botlink_v1_botlink_proto_rawDesc = "" +
 	"\n" +
 	"registered\x18\x01 \x01(\bR\n" +
 	"registered\x12\x1a\n" +
-	"\beligible\x18\x02 \x01(\bR\beligible2\xc4\x01\n" +
+	"\beligible\x18\x02 \x01(\bR\beligible\"\x80\x01\n" +
+	"\x14CreateInvoiceCommand\x12\x14\n" +
+	"\x05title\x18\x01 \x01(\tR\x05title\x12 \n" +
+	"\vdescription\x18\x02 \x01(\tR\vdescription\x12\x18\n" +
+	"\apayload\x18\x03 \x01(\tR\apayload\x12\x16\n" +
+	"\x06amount\x18\x04 \x01(\x03R\x06amount\"c\n" +
+	"\x12PreCheckoutRequest\x12\x19\n" +
+	"\border_id\x18\x01 \x01(\tR\aorderId\x12\x16\n" +
+	"\x06amount\x18\x02 \x01(\x03R\x06amount\x12\x1a\n" +
+	"\bcurrency\x18\x03 \x01(\tR\bcurrency\"=\n" +
+	"\x13PreCheckoutResponse\x12\x0e\n" +
+	"\x02ok\x18\x01 \x01(\bR\x02ok\x12\x16\n" +
+	"\x06reason\x18\x02 \x01(\tR\x06reason\"\xb1\x01\n" +
+	"\x15ForwardPaymentRequest\x12\x19\n" +
+	"\border_id\x18\x01 \x01(\tR\aorderId\x12;\n" +
+	"\x1atelegram_payment_charge_id\x18\x02 \x01(\tR\x17telegramPaymentChargeId\x12\x16\n" +
+	"\x06amount\x18\x03 \x01(\x03R\x06amount\x12(\n" +
+	"\x10telegram_user_id\x18\x04 \x01(\x03R\x0etelegramUserId\"4\n" +
+	"\x16ForwardPaymentResponse\x12\x1a\n" +
+	"\bcredited\x18\x01 \x01(\bR\bcredited2\x99\x03\n" +
 	"\aBotLink\x12D\n" +
 	"\x04Link\x12\x1c.scrabble.botlink.v1.FromBot\x1a\x1a.scrabble.botlink.v1.ToBot(\x010\x01\x12s\n" +
-	"\x16ResolveChatEligibility\x12+.scrabble.botlink.v1.ChatEligibilityRequest\x1a,.scrabble.botlink.v1.ChatEligibilityResponseB)Z'scrabble/pkg/proto/botlink/v1;botlinkv1b\x06proto3"
+	"\x16ResolveChatEligibility\x12+.scrabble.botlink.v1.ChatEligibilityRequest\x1a,.scrabble.botlink.v1.ChatEligibilityResponse\x12h\n" +
+	"\x13ValidatePreCheckout\x12'.scrabble.botlink.v1.PreCheckoutRequest\x1a(.scrabble.botlink.v1.PreCheckoutResponse\x12i\n" +
+	"\x0eForwardPayment\x12*.scrabble.botlink.v1.ForwardPaymentRequest\x1a+.scrabble.botlink.v1.ForwardPaymentResponseB)Z'scrabble/pkg/proto/botlink/v1;botlinkv1b\x06proto3"
 
 var (
 	file_botlink_v1_botlink_proto_rawDescOnce sync.Once
@@ -619,7 +976,7 @@ func file_botlink_v1_botlink_proto_rawDescGZIP() []byte {
 	return file_botlink_v1_botlink_proto_rawDescData
 }
 
-var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 8)
+var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
 var file_botlink_v1_botlink_proto_goTypes = []any{
 	(*FromBot)(nil),                     // 0: scrabble.botlink.v1.FromBot
 	(*ToBot)(nil),                       // 1: scrabble.botlink.v1.ToBot
@@ -629,27 +986,37 @@ var file_botlink_v1_botlink_proto_goTypes = []any{
 	(*ChatGateCommand)(nil),             // 5: scrabble.botlink.v1.ChatGateCommand
 	(*ChatEligibilityRequest)(nil),      // 6: scrabble.botlink.v1.ChatEligibilityRequest
 	(*ChatEligibilityResponse)(nil),     // 7: scrabble.botlink.v1.ChatEligibilityResponse
-	(*v1.NotifyRequest)(nil),            // 8: scrabble.telegram.v1.NotifyRequest
-	(*v1.SendToUserRequest)(nil),        // 9: scrabble.telegram.v1.SendToUserRequest
-	(*v1.SendToGameChannelRequest)(nil), // 10: scrabble.telegram.v1.SendToGameChannelRequest
+	(*CreateInvoiceCommand)(nil),        // 8: scrabble.botlink.v1.CreateInvoiceCommand
+	(*PreCheckoutRequest)(nil),          // 9: scrabble.botlink.v1.PreCheckoutRequest
+	(*PreCheckoutResponse)(nil),         // 10: scrabble.botlink.v1.PreCheckoutResponse
+	(*ForwardPaymentRequest)(nil),       // 11: scrabble.botlink.v1.ForwardPaymentRequest
+	(*ForwardPaymentResponse)(nil),      // 12: scrabble.botlink.v1.ForwardPaymentResponse
+	(*v1.NotifyRequest)(nil),            // 13: scrabble.telegram.v1.NotifyRequest
+	(*v1.SendToUserRequest)(nil),        // 14: scrabble.telegram.v1.SendToUserRequest
+	(*v1.SendToGameChannelRequest)(nil), // 15: scrabble.telegram.v1.SendToGameChannelRequest
 }
 var file_botlink_v1_botlink_proto_depIdxs = []int32{
 	2,  // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
 	4,  // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
 	3,  // 2: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
-	8,  // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
-	9,  // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
-	10, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
+	13, // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
+	14, // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
+	15, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
 	5,  // 6: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand
-	0,  // 7: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
-	6,  // 8: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
-	1,  // 9: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
-	7,  // 10: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
-	9,  // [9:11] is the sub-list for method output_type
-	7,  // [7:9] is the sub-list for method input_type
-	7,  // [7:7] is the sub-list for extension type_name
-	7,  // [7:7] is the sub-list for extension extendee
-	0,  // [0:7] is the sub-list for field type_name
+	8,  // 7: scrabble.botlink.v1.Command.create_invoice:type_name -> scrabble.botlink.v1.CreateInvoiceCommand
+	0,  // 8: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
+	6,  // 9: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
+	9,  // 10: scrabble.botlink.v1.BotLink.ValidatePreCheckout:input_type -> scrabble.botlink.v1.PreCheckoutRequest
+	11, // 11: scrabble.botlink.v1.BotLink.ForwardPayment:input_type -> scrabble.botlink.v1.ForwardPaymentRequest
+	1,  // 12: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
+	7,  // 13: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
+	10, // 14: scrabble.botlink.v1.BotLink.ValidatePreCheckout:output_type -> scrabble.botlink.v1.PreCheckoutResponse
+	12, // 15: scrabble.botlink.v1.BotLink.ForwardPayment:output_type -> scrabble.botlink.v1.ForwardPaymentResponse
+	12, // [12:16] is the sub-list for method output_type
+	8,  // [8:12] is the sub-list for method input_type
+	8,  // [8:8] is the sub-list for extension type_name
+	8,  // [8:8] is the sub-list for extension extendee
+	0,  // [0:8] is the sub-list for field type_name
 }
 
 func init() { file_botlink_v1_botlink_proto_init() }
@@ -666,6 +1033,7 @@ func file_botlink_v1_botlink_proto_init() {
 		(*Command_SendToUser)(nil),
 		(*Command_SendToChannel)(nil),
 		(*Command_ChatGate)(nil),
+		(*Command_CreateInvoice)(nil),
 	}
 	type x struct{}
 	out := protoimpl.TypeBuilder{
@@ -673,7 +1041,7 @@ func file_botlink_v1_botlink_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_botlink_v1_botlink_proto_rawDesc), len(file_botlink_v1_botlink_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   8,
+			NumMessages:   13,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

pkg/proto/botlink/v1/botlink.proto

@@ -27,6 +27,24 @@ service BotLink {
   // same mTLS channel when a user joins the chat, to decide whether to grant the
   // write permission. Delivery of the answer is request/response (not best-effort).
   rpc ResolveChatEligibility(ChatEligibilityRequest) returns (ChatEligibilityResponse);
+
+  // ValidatePreCheckout answers whether a Telegram Stars pre_checkout_query may be
+  // approved before any star is charged: the order in the invoice payload exists, is
+  // still creditable (pending or an honoured-expired order, never one already paid),
+  // and its amount and currency match the invoice. The bot calls it on every
+  // pre_checkout_query and approves only on ok; a not-ok answer or a channel failure
+  // declines the charge (fail-closed). Reusable Stars invoice links make this gate the
+  // one place a repeat payment is stopped before money moves. Request/response.
+  rpc ValidatePreCheckout(PreCheckoutRequest) returns (PreCheckoutResponse);
+
+  // ForwardPayment delivers a completed Telegram Stars payment from the bot's durable
+  // outbox to the gateway for crediting. The bot calls it (retrying until it gets a
+  // response) after Telegram confirms the payment; the gateway forwards it to the
+  // backend intake, which credits the order once, idempotent on
+  // telegram_payment_charge_id. A response means the payment was durably handled
+  // (credited, or recorded as unmatched) and the bot may forget the outbox row; a
+  // transport error leaves the row for a later retry. Request/response.
+  rpc ForwardPayment(ForwardPaymentRequest) returns (ForwardPaymentResponse);
 }
 
 // FromBot is a message the bot sends to the gateway: the opening Hello, then one
@@ -61,17 +79,21 @@ message Command {
     scrabble.telegram.v1.SendToUserRequest send_to_user = 3;
     scrabble.telegram.v1.SendToGameChannelRequest send_to_channel = 4;
     ChatGateCommand chat_gate = 5;
+    CreateInvoiceCommand create_invoice = 6;
   }
 }
 
 // Ack reports the outcome of the Command with command_id. delivered mirrors the
 // connector delivery semantics (false when the kind is not rendered out-of-app, the
 // user never started the bot, or no channel is configured); error carries an
-// unexpected transport/render failure, distinct from a clean not-delivered.
+// unexpected transport/render failure, distinct from a clean not-delivered. result
+// carries a command's return value when it has one (the created invoice link for a
+// create_invoice command); it is empty otherwise.
 message Ack {
   string command_id = 1;
   bool delivered = 2;
   string error = 3;
+  string result = 4;
 }
 
 // ChatGateCommand sets a Telegram user's write access in the moderated discussion
@@ -99,3 +121,48 @@ message ChatEligibilityResponse {
   bool registered = 1;
   bool eligible = 2;
 }
+
+// CreateInvoiceCommand asks the bot to mint a Telegram Stars invoice link for a
+// pending order (createInvoiceLink in XTR). payload is the order id, which Telegram
+// echoes back in the pre_checkout_query and the successful_payment; amount is the
+// price in whole stars; title and description are shown on the invoice. The bot
+// returns the link in its Ack result.
+message CreateInvoiceCommand {
+  string title = 1;
+  string description = 2;
+  string payload = 3;
+  int64 amount = 4;
+}
+
+// PreCheckoutRequest asks whether a Stars pre_checkout_query for order_id at amount
+// (whole stars) in currency may be approved before the charge.
+message PreCheckoutRequest {
+  string order_id = 1;
+  int64 amount = 2;
+  string currency = 3;
+}
+
+// PreCheckoutResponse is the approval answer. ok approves the charge; reason carries a
+// short user-facing decline message when ok is false.
+message PreCheckoutResponse {
+  bool ok = 1;
+  string reason = 2;
+}
+
+// ForwardPaymentRequest carries a completed Stars payment: order_id from the invoice
+// payload, the Telegram charge id (the idempotency key), the amount in whole stars,
+// and the payer's Telegram user id.
+message ForwardPaymentRequest {
+  string order_id = 1;
+  string telegram_payment_charge_id = 2;
+  int64 amount = 3;
+  int64 telegram_user_id = 4;
+}
+
+// ForwardPaymentResponse reports the durable outcome. credited is true when the order
+// was credited (or already had been); false means the payment was recorded but could
+// not be matched to a creditable order (an operator follows up). Either way the bot
+// may forget the outbox row — only a transport error triggers a retry.
+message ForwardPaymentResponse {
+  bool credited = 1;
+}

pkg/proto/botlink/v1/botlink_grpc.pb.go

@@ -28,6 +28,8 @@ const _ = grpc.SupportPackageIsVersion9
 const (
 	BotLink_Link_FullMethodName                   = "/scrabble.botlink.v1.BotLink/Link"
 	BotLink_ResolveChatEligibility_FullMethodName = "/scrabble.botlink.v1.BotLink/ResolveChatEligibility"
+	BotLink_ValidatePreCheckout_FullMethodName    = "/scrabble.botlink.v1.BotLink/ValidatePreCheckout"
+	BotLink_ForwardPayment_FullMethodName         = "/scrabble.botlink.v1.BotLink/ForwardPayment"
 )
 
 // BotLinkClient is the client API for BotLink service.
@@ -48,6 +50,22 @@ type BotLinkClient interface {
 	// same mTLS channel when a user joins the chat, to decide whether to grant the
 	// write permission. Delivery of the answer is request/response (not best-effort).
 	ResolveChatEligibility(ctx context.Context, in *ChatEligibilityRequest, opts ...grpc.CallOption) (*ChatEligibilityResponse, error)
+	// ValidatePreCheckout answers whether a Telegram Stars pre_checkout_query may be
+	// approved before any star is charged: the order in the invoice payload exists, is
+	// still creditable (pending or an honoured-expired order, never one already paid),
+	// and its amount and currency match the invoice. The bot calls it on every
+	// pre_checkout_query and approves only on ok; a not-ok answer or a channel failure
+	// declines the charge (fail-closed). Reusable Stars invoice links make this gate the
+	// one place a repeat payment is stopped before money moves. Request/response.
+	ValidatePreCheckout(ctx context.Context, in *PreCheckoutRequest, opts ...grpc.CallOption) (*PreCheckoutResponse, error)
+	// ForwardPayment delivers a completed Telegram Stars payment from the bot's durable
+	// outbox to the gateway for crediting. The bot calls it (retrying until it gets a
+	// response) after Telegram confirms the payment; the gateway forwards it to the
+	// backend intake, which credits the order once, idempotent on
+	// telegram_payment_charge_id. A response means the payment was durably handled
+	// (credited, or recorded as unmatched) and the bot may forget the outbox row; a
+	// transport error leaves the row for a later retry. Request/response.
+	ForwardPayment(ctx context.Context, in *ForwardPaymentRequest, opts ...grpc.CallOption) (*ForwardPaymentResponse, error)
 }
 
 type botLinkClient struct {
@@ -81,6 +99,26 @@ func (c *botLinkClient) ResolveChatEligibility(ctx context.Context, in *ChatElig
 	return out, nil
 }
 
+func (c *botLinkClient) ValidatePreCheckout(ctx context.Context, in *PreCheckoutRequest, opts ...grpc.CallOption) (*PreCheckoutResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(PreCheckoutResponse)
+	err := c.cc.Invoke(ctx, BotLink_ValidatePreCheckout_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *botLinkClient) ForwardPayment(ctx context.Context, in *ForwardPaymentRequest, opts ...grpc.CallOption) (*ForwardPaymentResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ForwardPaymentResponse)
+	err := c.cc.Invoke(ctx, BotLink_ForwardPayment_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // BotLinkServer is the server API for BotLink service.
 // All implementations must embed UnimplementedBotLinkServer
 // for forward compatibility.
@@ -99,6 +137,22 @@ type BotLinkServer interface {
 	// same mTLS channel when a user joins the chat, to decide whether to grant the
 	// write permission. Delivery of the answer is request/response (not best-effort).
 	ResolveChatEligibility(context.Context, *ChatEligibilityRequest) (*ChatEligibilityResponse, error)
+	// ValidatePreCheckout answers whether a Telegram Stars pre_checkout_query may be
+	// approved before any star is charged: the order in the invoice payload exists, is
+	// still creditable (pending or an honoured-expired order, never one already paid),
+	// and its amount and currency match the invoice. The bot calls it on every
+	// pre_checkout_query and approves only on ok; a not-ok answer or a channel failure
+	// declines the charge (fail-closed). Reusable Stars invoice links make this gate the
+	// one place a repeat payment is stopped before money moves. Request/response.
+	ValidatePreCheckout(context.Context, *PreCheckoutRequest) (*PreCheckoutResponse, error)
+	// ForwardPayment delivers a completed Telegram Stars payment from the bot's durable
+	// outbox to the gateway for crediting. The bot calls it (retrying until it gets a
+	// response) after Telegram confirms the payment; the gateway forwards it to the
+	// backend intake, which credits the order once, idempotent on
+	// telegram_payment_charge_id. A response means the payment was durably handled
+	// (credited, or recorded as unmatched) and the bot may forget the outbox row; a
+	// transport error leaves the row for a later retry. Request/response.
+	ForwardPayment(context.Context, *ForwardPaymentRequest) (*ForwardPaymentResponse, error)
 	mustEmbedUnimplementedBotLinkServer()
 }
 
@@ -115,6 +169,12 @@ func (UnimplementedBotLinkServer) Link(grpc.BidiStreamingServer[FromBot, ToBot])
 func (UnimplementedBotLinkServer) ResolveChatEligibility(context.Context, *ChatEligibilityRequest) (*ChatEligibilityResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method ResolveChatEligibility not implemented")
 }
+func (UnimplementedBotLinkServer) ValidatePreCheckout(context.Context, *PreCheckoutRequest) (*PreCheckoutResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ValidatePreCheckout not implemented")
+}
+func (UnimplementedBotLinkServer) ForwardPayment(context.Context, *ForwardPaymentRequest) (*ForwardPaymentResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ForwardPayment not implemented")
+}
 func (UnimplementedBotLinkServer) mustEmbedUnimplementedBotLinkServer() {}
 func (UnimplementedBotLinkServer) testEmbeddedByValue()                 {}
 
@@ -161,6 +221,42 @@ func _BotLink_ResolveChatEligibility_Handler(srv interface{}, ctx context.Contex
 	return interceptor(ctx, in, info, handler)
 }
 
+func _BotLink_ValidatePreCheckout_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(PreCheckoutRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(BotLinkServer).ValidatePreCheckout(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: BotLink_ValidatePreCheckout_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(BotLinkServer).ValidatePreCheckout(ctx, req.(*PreCheckoutRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _BotLink_ForwardPayment_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ForwardPaymentRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(BotLinkServer).ForwardPayment(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: BotLink_ForwardPayment_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(BotLinkServer).ForwardPayment(ctx, req.(*ForwardPaymentRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // BotLink_ServiceDesc is the grpc.ServiceDesc for BotLink service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -172,6 +268,14 @@ var BotLink_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "ResolveChatEligibility",
 			Handler:    _BotLink_ResolveChatEligibility_Handler,
 		},
+		{
+			MethodName: "ValidatePreCheckout",
+			Handler:    _BotLink_ValidatePreCheckout_Handler,
+		},
+		{
+			MethodName: "ForwardPayment",
+			Handler:    _BotLink_ForwardPayment_Handler,
+		},
 	},
 	Streams: []grpc.StreamDesc{
 		{