Filecoin协议Go开发包

1、Filecoin.Go开发包概述

Filecoin.Go 开发包适用于为Go语言开发的应用快速增加对Filecoin/FIL数字资产的支持能力， 即支持使用自有Filecoin区块链节点的应用场景，也支持基于第三方公共节点的 轻量级部署场景。

Filecoin.Go开发包主要包含以下特性：

• 支持离线生成Filecoin地址，方便管理维护
• 支持Filecoin消息的离线签名，有利于更好地保护私钥
• 自动估算Filecoin消息的GAS参数，避免手工调整
• 支持使用自有节点或第三方节点，例如使用Infura提供的公共节点
• 完善的Filecoin节点API封装，支持全部RPC API调用，例如查询地址地历史消息等

Filecoin.Go开发包采用 Go 1.15 开发，主要数据结构及关系如下图所示：

Filecoin.Go开发包的当前版本1.0.0，主要代码文件清单如下：

2、使用示例代码

2.1 创建新地址

在终端进入演示代码目录，执行如下命令：

~$ cd ~/filecoin.go/demo
~/filecoin.go/demo$ go run new-address-demo.go

执行结果如下：

2.2 利用私钥恢复地址

在终端进入演示代码目录，执行如下命令：

~$ cd ~/filecoin.go/demo
~/filecoin.go/demo$ go run restore-address-demo.go

执行结果如下：

2.3 FIL转账及余额查询

在终端进入演示代码目录，执行如下命令：

~$ cd ~/filecoin.go/demo
~/filecoin.go/demo$ go run fil-transfer-demo.go

执行结果如下：

2.4 RPC客户端调用示例

在终端进入演示代码目录，执行如下命令：

~$ cd ~/filecoin.go/demo
~/filecoin.go/demo$ go run client-demo.go

执行结果如下：

2.5 到账监控演示

在终端进入演示代码目录，执行如下命令：

~$ cd ~/filecoin.go/demo
~/filecoin.go/demo$ go run monitor-demo.go

启动程序后，如果监听的地址有到账消息，将在终端显示消息内容：

3、使用Filecoin.Go

Kit是开发包的入口，使用这个类可以快速实现FIL转账、交易确认等待和余额查询等功能。

3.1 实例化Kit

Kit实例化需要传入Client对象和Credential对象，这两个 参数分别封装了Filecoin节点提供的API，以及进行交易签名的用户身份信息。

例如，下面的代码创建一个接入Infura的Filecoin节点的Kit实例，并使用 指定的私钥进行交易签名：

//import "fmt"
//import "net/http"
//import "filtool/filecoin"

url := "https://project_id:project_secret@filecoin.infura.io" // 使用你的project id/secret替换
client, _ := filecoin.NewClient(url, http.Header{})           // 创建RPC Client对象
credential, _ := filecoin.RestoreCredential("01a7...15f1")    // 使用你的私钥替换
kit := filecoin.NewKit(client, credential)                    // 创建FilKit实例

在创建FilKit实例时指定的Credential对象，将作为默认身份凭证执行 后续的转账交易等操作。

• Client / RPC客户端

如果使用的Filecoin节点无需身份认证，那么在创建 RpcClient时只需传入RPC URL和一个空的http.Header对象。例如使用本机的filecoin节点：

//import "filtool/filecoin"

client, _ := filecoin.NewClient("http://127.0.0.1/rpc/v0", http.Header{})  // 连接本机节点

如果使用的Filecoin节点启用了授权TOKEN的认证机制，那么在创建RpcClient 时需要传入授权TOKEN，例如：

//import "filtool/filecoin"

authToken := "Ynl0ZSBhcnJheQ=="                                           // 节点分配的授权TOKEN
headers := http.Header{"Authorization": []string{"Bearer " + authToken}}  // 请求需要携带的Http 头数据
client, _ := new RpcClient("http://234.10.58.147/rpc/v0", headers)

• Credential / 身份凭证

如果已有的私钥是16进制字符串形式，那么使用filecoin的方法RestoreCredential()来创建 实例对象，例如：

//import "filtool/filecoin"

credential, _ := filecoin.RestoreCredentail(
  "01a70dc929dfabd71d22707565452f2495537aa688ecb396f44717dd410315f1"  // 16进制字符串格式的私钥
)

3.2 FIL转账交易

使用Kit的Transfer()方法进行FIL转账，例如发送 1.23 FIL ：

//import "fmt"
//import "filtool/filecoin"

to := "f1saxri7cpyz2cm767q77u3mqumrggljrmi5iqdty"          // 转账目标地址
amount := "1230000000000000000"                            // 最小单位的转账数量，1 FIL = 10^18 UNIT
cid, _ := kit.Transfer(to, amount)                         // 提交Trx转账交易
fmt.Printf("txid => %+v\n",  cid)                          // 显示交易ID

注意 ：

• 转账数量应转换为最小单位计量的整数字符串，1 FIL = 10^18 最小单位。
• 支持各种类型的接收地址，例如：
  • f01729：ID地址：
  • f17uoq6tp427uzv7fztkbsnn64iwotfrristwpryy：SECP256K1地址
  • f24vg6ut43yw2h2jqydgbg2xq7x6f4kub3bg6as6i：ACTOR地址
  • f3q22fijmmlckhl56rn5nkyamkph3mcfu5ed6dheq53：BLS地址

3.3 等待Filecoin消息确认

使用FilKit的WaitForReceipt()方法等待交易确认，例如：

//import "fmt"
//import "filtool/filecoin"

receipt, _ := kit.WaitForReceipt(cid, 60)                   // 等待消息收据60秒
fmt.Printf("receipt => %+v\n", receipt)                     // 显示消息手续，ExitCode为0表示成功

3.4 指定地址的FIL余额查询

使用GetBalance()方法查询指定地址的FIL余额，例如：

//import "fmt"
//import "filtool/filecoin"

addr := 'f1saxri7cpyz2cm767q77u3mqumrggljrmi5iqdty'         // 要查询的Filecoin地址
balance, _ := kit.GetBlanace(addr)                          // 查询FIL余额，最小单位表示
fmt.Printf("balance => %+v\n", balance)                     // 显示FIL余额

注意 ：返回的余额为最小单位表示，1 FIL = 10^18最小单位。

3.5 使用RPC客户端

Filecoin节点透过其RPC API接口提供了很多有用的功能，使用Filecoin.Go 开发包的RpcClient类可以访问所有的Filecoin RPC API。 例如查询当前的链头TipSet，对应的RPC API为Filecoin.ChainHead， 使用Client对象的调用代码如下：

//import "fmt"
//import "context"
//import "filtool/filecoin"

client, _ := filecoin.NewClient("http://127.0.0.1:1234/rpc/v0", http.Header{}) // 创建Client对象

tipset, _ := client.ChainHead(context.Background())                            // 调用Filecoin.ChainHead API
fmt.Printf("height => %d\n", tipset.Height())                                  // 显示当前高度

3.6 使用Monitor

Monitor类用来监视指定地址的到账消息。使用Monitor的步骤为：

• 创建Monitor实例
• 使用WatchAddress()或WatchAddressSinceNow()添加要监听到账的地址
• 使用AddListener()添加到账通知回调函数，当所监听的地址发生到账消息后，Monitor将触发回调函数
• 使用Run()启动Monitor持续运行

可以使用Kit对象的GetMonitor()方法得到一个Monitor实例，也可以单独初始化，例如：

//import "filtool/filecoin"

client, _ := filecoin.NewClient("http://127.0.0.1:1234/rpc/v0", http.Header{}) // 创建Client对象
monitor := filecoin.NewMonitor(client)                                         // 创建Monitor对象

使用Monitor的WatchAddressSinceNow()方法添加一个从当前高度开始监视到账消息的地址，例如：

monitor.WatchAddressSinceNow("f14jzpfkx6hdiq6wf72lbiclfysz3mj6z4sdvunti")    // 从当前高度开始监视

也可以指定监视的起始高度，例如从高度10000开始监视：

monitor.WatchAddress("f14jzpfkx6hdiq6wf72lbiclfysz3mj6z4sdvunti", 10000)     // 从高度10000开始监视

Monitor使用回调函数通知应用有到账消息。使用Monitor的AddListener()方法添加一个 到账消息回调函数，例如下面代码添加一个回调函数，它只是简单的输出到账消息：

//import "fmt"
//import "fitool/filecoin"

monitor.AddListener(func(comboMsgs []*filecoin.ComboMsg){
  for _, comboMsg := range comboMsgs {
    fmt.Printf("msg => %+v\n", comboMsg)
  }
})

一旦设置好要监听的地址并添加了通知回调，就可以调用Run()方法启动监听了，例如：

monitor.Run()