Filecoin/FIL Golang开发包

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

1、Filecoin.Go开发包概述

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

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

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

filecoin.go

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

代码文件说明
filecoin/kit.goFilecoin.Go开发包入口类
filecoin/client.goFilecoin节点RPC客户端类
filecoin/credential.goFilecoin区块链身份凭证类
filecoin/address.goFilecoin节点地址类
filecoin/monitor.goFilecoin到账监听类
filecoin/types.goFilecoin类型定义
demo/new-address-demo.go演示代码,创建新的Filecoin区块链地址
demo/restore-address-demo.go演示代码,使用已有私钥重新生成Filecoin地址
demo/fil-transfer-demo.go演示代码,FILE转账和余额查询
demo/client-demo.go演示代码,链头信息查询等RPC API调用
demo/monitor-demo.go演示代码,监听指定地址的到账消息
go.modGo模块管理文件

2、使用示例代码

2.1 创建新地址

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

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

执行结果如下:

filecoin.go

2.2 利用私钥恢复地址

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

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

执行结果如下:

filecoin.go

2.3 FIL转账及余额查询

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

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

执行结果如下:

filecoin.go

2.4 RPC客户端调用示例

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

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

执行结果如下:

filecoin.go

2.5 到账监控演示

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

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

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

filecoin.go

3、使用Filecoin.Go

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

3.1 实例化Kit

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

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

1
2
3
4
5
6
7
8
//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节点:

1
2
3
//import "filtool/filecoin"

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

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

1
2
3
4
5
//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()来创建 实例对象,例如:

1
2
3
4
5
//import "filtool/filecoin"

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

3.2 FIL转账交易

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

1
2
3
4
5
6
7
//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()方法等待交易确认,例如:

1
2
3
4
5
//import "fmt"
//import "filtool/filecoin"

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

3.4 指定地址的FIL余额查询

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

1
2
3
4
5
6
//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对象的调用代码如下:

1
2
3
4
5
6
7
8
//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实例,也可以单独初始化,例如:

1
2
3
4
//import "filtool/filecoin"

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

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

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

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

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

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

1
2
3
4
5
6
7
8
//import "fmt"
//import "fitool/filecoin"

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

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

1
monitor.Run()

Filecoin.Go官方下载地址:http://sc.hubwiz.com/codebag/filecoin-go-lib/