如何在 TON 区块链上用 FunC 和 Blueprint 打造红包智能合约（第一部分）

riyad

今天，我将带大家一起探索如何在 TON 区块链上用 FunC 语言和 Blueprint 工具开发一个红包智能合约。这篇教程是第一部分，重点介绍项目搭建、合约编写和成功编译的过程。我会分享完整的代码和项目结构，适合对 TON 开发感兴趣的新手。让我们开始吧！

. [8 {9 a+ R8 |0 d5 F( r0 N5 k

什么是 TON 和红包合约？

TON（The Open Network）是一个高效的区块链平台，以低成本和高吞吐量著称，非常适合开发去中心化应用。红包是中国文化中常见的分享方式，我想通过智能合约实现一个简单功能：用户存入 TON，指定份数，其他人可以领取。这篇文章将展示我到目前为止的进展——编写并成功编译合约。

准备工作

在动手之前，确保你的环境准备好：

安装 Node.js：Blueprint 依赖 Node.js，建议使用最新 LTS 版本，从 nodejs.org 下载安装。

安装 Blueprint：在终端运行以下命令全局安装：

1. npm i @ton/blueprint

复制代码

代码编辑器：我用的是 VS Code，安装 TON FunC 插件可以高亮语法，提升编码体验。

步骤 1：创建项目

我们用 Blueprint 初始化一个 TON 项目。打开终端，输入：

1. npm create ton@latest

复制代码

项目名称：我输入了 redpacket。

模板：选择 func-empty，因为我想从头写合约。

创建完成后，进入项目目录：

1. cd redpacket

复制代码

项目文件夹结构

Blueprint 生成的项目结构非常清晰，以下是 redpacket 文件夹的内容：

  
5 \# y$ W6 ?2 c, ^* {7 c5 V

         

步骤 2：编写红包合约代码

在 contracts/redpacket.fc 中，我编写了红包智能合约。以下是代码和详细注释：

1. #include "imports/stdlib.fc";
   
2. 
   / w% T5 r/ h) ]% Y
3. // 准备内部消息的函数
   ) y9 P5 D1 Y0 l( Z9 N6 C
4. (cell) prepare_internal_msg(slice recipient, int amount, int bounce) {
   : ~# S# |& V) m" o- c1 D
5.     return begin_cell()
   
6.         .store_uint(0, 4)  ;; 内部消息标记 (0x0)
   4 G  H0 S1 b' }: F" I. |- B0 v0 s
7.         .store_slice(recipient)  ;; 目标地址
   
8.         .store_coins(amount)  ;; 发送金额
   5 H" B0 B% l& f2 m7 x+ Q' b+ e
9.         .store_uint(bounce, 1)  ;; 是否可退回标志
   + [% _4 O$ i. V5 P  S  F1 N
10.         .store_uint(0, 1 + 4 + 4)  ;; ihr_disabled: 0, 无源地址和目标地址扩展
    
11.         .store_uint(0, 64)  ;; ihr_fee
    
12.         .store_uint(0, 64)  ;; fwd_fee
    
13.         .store_uint(0, 64)  ;; 创建逻辑时间
    + r9 {3 j* [5 q9 F9 z7 v4 K$ |4 @% I
14.         .store_uint(0, 64)  ;; 创建时间戳
    
15.         .store_uint(0, 1)  ;; 无状态初始化
    
16.         .store_uint(0, 1)  ;; 消息体为空
    6 P6 W/ f+ r  B9 X9 }
17.     .end_cell();
    8 x* A" L0 y# h# L+ ~$ u
18. }
    
19. 
    7 L) |: k, u2 R0 L8 O8 j
20. // 处理内部消息的主函数
    
21. () recv_internal(int my_balance, int msg_value, cell in_msg_full, slice in_msg_body) impure {
    9 i, @9 @1 t1 F7 n4 V% H% W4 h
22.     ;; 检查合约是否有余额可用
    0 C& m: C$ Z* g  H8 I4 P3 o
23.     if (my_balance <= 0) { throw(100); }
    
24. 
    - Q& p* S. c# v
25.     ;; 解析传入消息
    9 i$ V; V# h: N  F6 J* U0 P- D
26.     var parser = in_msg_full.begin_parse();
    
27.     int flags = parser~load_uint(4);
    ( i, b5 s8 F3 {  v" _1 U& i
28.     slice sender_address = parser~load_msg_addr();
    
29.     int sender_hash = sender_address.slice_hash();
    
30. 
    ( A0 @# y* g/ c! u/ O% A* }
31.     ;; 加载持久化存储（红包字典）
    ; a( C+ b" O' ]! z* b  E
32.     var data = get_data();
    1 g2 m9 R, Y" Y* l1 c) z
33.     cell red_packets = new_dict();
    
34.     if (~ slice_empty?(data.begin_parse())) {
    ' R/ p0 m  w. q* |2 l
35.         var data_slice = data.begin_parse();
    
36.         red_packets = data_slice~load_dict();
    
37.     }
    
38. 
    8 G3 p! c! k% E3 l# j7 W0 G$ Y# d5 X
39.     ;; 检查消息体是否有操作（创建或领取）
    
40.     if (~ slice_empty?(in_msg_body)) {
    / M6 n8 N0 a0 u4 i# l2 A
41.         var body_parser = in_msg_body;
    
42.         int op = body_parser~load_uint(8);  ;; 操作码：1 = 创建，2 = 领取
    # K( s$ ]" u0 N- _9 m  S: r$ g+ V
43.         int red_packet_id = body_parser~load_uint(256);  ;; 红包唯一ID
    
44. 
    
45.         if ((op == 1) & (msg_value > 0)) {  ;; 创建新红包
    5 |* g  R5 u! I/ r; t6 K
46.             int claim_amount = body_parser~load_int(256);  ;; 发送者指定每份领取金额
    
47.             if ((claim_amount <= 0) | (claim_amount > msg_value)) { throw(103); }  ;; 无效金额检查
    1 u& s0 t8 q! g- C
48. 
    $ t2 ]' b% {( e" V, s2 \( V* F
49.             var packet_data = begin_cell()
    
50.                 .store_int(msg_value, 256)  ;; 红包总金额
    
51.                 .store_int(claim_amount, 256)  ;; 每份领取金额
    
52.                 .store_dict(new_dict())  ;; 空领取记录字典
    6 @. _' h5 k6 h- \8 }5 l: ^
53.             .end_cell();
    & p+ i6 Z: L+ k. b& S
54. 
    
55.             red_packets = udict_set_ref(red_packets, 256, red_packet_id, packet_data);
    
56.             set_data(begin_cell().store_dict(red_packets).end_cell());
    8 O# T$ N8 L* s0 Q) J! }
57.             return ();
    + k3 }0 F  \# e. B% i  C  C
58.         } else {
    
59.             if (op == 2) {  ;; 领取红包
    
60.                 var (packet_cell, exists) = udict_get_ref?(red_packets, 256, red_packet_id);
    2 X: \8 b) X% S9 J0 N
61.                 if (exists == 0) { throw(104); }  ;; 红包不存在
    ( ?7 m1 B3 O: r/ @( b" P
62. 
    6 J  D9 B' n* M, O. j, i& W+ c! r+ P
63.                 var packet_parser = packet_cell.begin_parse();
    
64.                 int stored_balance = packet_parser~load_int(256);
    7 L6 q7 \, o' _% E* P" f
65.                 int claim_amount = packet_parser~load_int(256);
    6 e7 D. _4 v* Z/ @/ R( {
66.                 cell claimed = packet_parser~load_dict();
    & N: U( `% s0 d) _( N' O
67. 
    ( T5 ?' z" b1 [& W+ @8 v1 h
68.                 ;; 检查发送者是否已领取
    : N, c8 A2 P1 t( y" o+ z/ N7 l3 U3 Z5 Q
69.                 var (claimed_value, claimed_exists) = udict_get_ref?(claimed, 256, sender_hash);
    : u" l2 w& n/ A6 S
70.                 if (claimed_exists == 1) { throw(101); }  ;; 已领取过
    ; \  u5 j8 y1 P/ V8 ?- q8 H( K
71. 
    8 [/ E4 U4 Z8 G& D- b! t
72.                 ;; 检查余额是否足够
    
73.                 if (stored_balance < claim_amount) { throw(102); }  ;; 余额不足
    " {1 ]# z1 u/ m( K* a
74. 
    , v9 w  k" `& L
75.                 ;; 更新红包状态
    . c* B- K) ^4 Z6 P! x
76.                 stored_balance = stored_balance - claim_amount;
    9 Y/ q0 A; y1 h! b5 p6 h
77.                 var value_cell = begin_cell().store_int(1, 8).end_cell();
    3 u/ X; \- [8 u2 M: w
78.                 claimed = udict_set_ref(claimed, 256, sender_hash, value_cell);
    1 S* l. o# o: e
79. 
    ) ]) D. P3 X3 K' B9 [3 A, u1 \; x: M0 D
80.                 ;; 保存更新后的红包数据
    ' \3 g+ i; ]' X$ `
81.                 red_packets = udict_set_ref(red_packets, 256, red_packet_id,
    
82.                     begin_cell()
    
83.                         .store_int(stored_balance, 256)
    
84.                         .store_int(claim_amount, 256)
    " J3 q- ?& V: p  ]' e7 C
85.                         .store_dict(claimed)
    
86.                     .end_cell());
    . T! R) y) ?" c4 s
87. 
    
88.                 set_data(begin_cell().store_dict(red_packets).end_cell());
    
89. 
    $ i% n' x0 W& w5 T6 R4 g: G/ H
90.                 ;; 将领取金额发送给用户
    
91.                 send_raw_message(
    " ]+ l2 a, X& P/ ^% U. q
92.                     prepare_internal_msg(sender_address, claim_amount, 1),
    : _- E# B) i* O: d, h
93.                     64  ;; 单独支付 gas 费用
    " r/ V0 F8 ]" e9 q8 X
94.                 );
    7 |" d, J, O3 G/ V7 e" P
95.                 return ();
    7 }" `; l! e" g% p2 j$ d9 \+ h
96.             }
    
97.         }
    + j; T7 k$ w* f
98.     }
    
99.     throw(105);  ;; 无效消息（未指定操作）
    
100. }
     8 K& t0 H9 S3 ]! |8 \5 V% U: U2 i: V
101. 
     
102. // 查询红包状态的外部方法
     2 ~6 C+ k) `) N& o
103. ([int, int, cell]) get_red_packet_data(int red_packet_id) method_id {
     
104.     var data = get_data();
     . @! R. x0 G0 K- u1 O$ |% s4 U) K& \
105.     cell red_packets = new_dict();
     
106.     if (~ slice_empty?(data.begin_parse())) {
     7 d% F. v5 f+ y; I
107.         var data_slice = data.begin_parse();
     
108.         red_packets = data_slice~load_dict();
     
109.     }
     ' x- w/ q' [8 N% _
110. 
     6 {2 v5 Y/ p# a: j( w  M" s) m
111.     var (packet_cell, exists) = udict_get_ref?(red_packets, 256, red_packet_id);
     
112.     if (exists == 0) {
     " `) B$ M3 u5 g1 F5 x' k7 w
113.         return [0, 0, new_dict()];
     
114.     }
     
115. 
     ! V. w! d4 j& N: l" Q
116.     var packet_parser = packet_cell.begin_parse();
     " L/ Y5 L: M5 c- L) q' M
117.     int stored_balance = packet_parser~load_int(256);
     
118.     int claim_amount = packet_parser~load_int(256);
     0 o3 k" k7 z, M/ d, ]
119.     cell claimed = packet_parser~load_dict();
     ! z1 ]5 m) M$ E: R9 U) k
120.     return [stored_balance, claim_amount, claimed];
     
121. }

复制代码

代码说明

1. prepare_internal_msg 函数

这个函数用于构造一个内部消息，用于将 TON 转账给领取者。

) `: a5 [1 F/ h9 y9 k+ o8 U8 Q

功能：生成一个标准的 TON 内部消息单元（cell），包含目标地址、金额和是否可退回等信息。

参数：

• recipient：目标地址（slice 类型）。
• amount：转账金额（单位：nanoTON）。
• bounce：是否可退回（1 表示可退回，0 表示不可退回）。
  1 l3 y. |+ V, s! C+ b

实现：

• 使用 begin_cell() 创建一个新的单元。
• 按 TON 消息格式依次存储：消息标记（0x0）、目标地址、金额、可退回标志等。
• 其他字段（如手续费、时间戳等）设为默认值 0。
  0 C  X# z+ m: Y- f4 x

用途：在领取红包时，将金额发送给用户时调用。

. A# W) _. I8 P2 |+ `) S( C( _/ H# Y

2. recv_internal 函数

这是合约的核心函数，处理所有内部消息，实现创建和领取红包的逻辑。

: P; c1 l) T+ v  G7 N2 j

功能：根据消息内容执行红包的创建或领取操作。

参数：

• my_balance：合约当前余额。
• msg_value：消息附带的 TON 金额。
• in_msg_full：完整消息单元。
• in_msg_body：消息体（操作指令）。
  

& ^. h; J9 p' s: [

实现：

• 余额检查：如果合约余额小于等于 0，抛出错误（代码 100）。
• 解析消息：提取发送者地址并计算其哈希值，用于记录领取状态。
• 加载存储：从合约持久化存储中读取红包字典（red_packets），如果为空则初始化一个新字典。
• 处理操作：
  

创建红包（op == 1）：

• 检查消息附带金额是否大于 0。
• 从消息体读取每份领取金额（claim_amount），并验证其有效性（大于 0 且不超过总金额）。
• 创建红包数据（总金额、每份金额、空领取记录），存储到字典中。
• 更新合约存储。
  . l( A/ p  d4 b& t% m9 V/ r

领取红包（op == 2）：

• 根据红包 ID 从字典中查找红包数据，若不存在则抛出错误（代码 104）。
• 解析红包数据：总余额、每份金额、已领取记录。
• 检查发送者是否已领取（若已领取则抛出错误 101）。
• 检查余额是否足够（不足则抛出错误 102）。
• 更新红包状态：扣除领取金额，记录发送者为已领取。
• 保存更新后的红包数据。
• 调用 prepare_internal_msg 发送领取金额给用户。
  ; e8 Q% |3 A+ v0 Q. j, B2 z

错误处理：如果消息体为空或操作无效，抛出错误（代码 105）。

, y7 l/ O/ w, k9 t

3. get_red_packet_data 函数

这是一个外部查询方法，用于查看某个红包的状态。

功能：返回指定红包的总余额、每份金额和领取记录。

参数：

• red_packet_id：红包唯一 ID。
  " L+ Q  r7 ?9 A7 c+ U* P% w' [, I

返回值：

• [stored_balance, claim_amount, claimed]：分别为红包剩余金额、每份领取金额和已领取记录字典。
  

实现：

• 从合约存储中读取红包字典。
• 根据红包 ID 查找对应数据，若不存在则返回默认值 [0, 0, new_dict()]。
• 解析红包数据并返回。
  

/ ]+ \7 L, I+ @0 a

这段代码实现了一个支持多红包的智能合约：

4 G& [! |6 ~  h+ Z' ~

• 用户可以用操作码 1 创建一个新红包，指定每份金额。
• 用户可以用操作码 2 领取指定红包，每次领取固定金额。
• 合约通过字典存储多个红包的状态，并防止重复领取。
• 提供外部查询方法查看红包详情。
  

; w, L1 V4 e0 I  l6 e$ c( T( Z
步骤 3：编译合约编写完成后，我运行以下命令编译代码：
/ B  A% P7 S4 \( X: r% C

1. npx blueprint build

复制代码

终端显示“Compilation successful”，证明代码语法正确，生成了字节码和 ABI 文件。以下是我编译成功的截图：

下一步计划
目前，我已经完成了合约的编写和编译，接下来我计划：

• 测试：用 Blueprint 的 Sandbox 在本地测试合约逻辑。
• 部署：将合约部署到 TON 测试网，验证实际效果。 这些内容会在后续教程中分享，敬请期待！
  

' ?' ^, q2 `' a. c6 U7 V$ N2 L总结
这篇教程展示了如何用 FunC 和 Blueprint 开始一个 TON 红包合约项目。到目前为止，我成功搭建了项目、编写了合约并编译通过。完整代码和文件夹结构都已分享，你可以跟着试试。如果你也想尝试 TON 开发，不妨从这个简单项目入手。有什么问题，欢迎留言交流！
' o$ w% U; T' O- C6 p  R/ ^