README
¶
go-fvm-sdk
go-fvm-sdk enables GO developers to write FVM contracts in TinyGo. To learn more about FVM, please check out resources on fvm forum.
Key features of go-fvm-sdk are...
- Compiles GO contracts into WASM
- Full compatibility with FVM system call interface
- unit/integration test support
- Deploy native WASM actor on FVM!
Why TinyGO
- Support most Go syntax and libraries.
- Smaller footprint which is great for use cases on the blockchain.
- Nimble management of GC and Memory, which is great for contracts with runtime constraints of tens to hundreds of milliseconds and memory constraints of a few megabytes.
Install
Install Gov1.20.x or above and TinyGov0.27 or above.
Note: latest Go or TinyGo versions may not be tested.
Use Binary
Go to releases and download the executables.
Rename your executable to fvm_go_sdk and add execution permission.
$ mv fvm_go_sdk_vX.Y.Z_xxx fvm_go_sdk
$ chmod +x fvm_go_sdk
Build from source
Install OpenCl and Rust.
Clone fvm_go_sdk repo and make.
$ sudo apt install ocl-icd-opencl-dev jq # install dependencies
$ cargo install cargo-edit # install cargo plugin, builtin-actor require
$ rustup target add wasm32-unknown-unknown # install wasm target
$ git clone git@github.com:ipfs-force-community/go-fvm-sdk.git
$ make
Note: it may take a while before you finish buiding from source.
Check if fvm_go_sdk is operational.
$ fvm_go_sdk -h
Once you have fvm_go_sdk ready, Go and TinyGo need to be patched in order to have the compiled WASM contract compatible with FVM.
$ fvm_go_sdk patch
Successful patching of go-fvm-sdk will give the following output. And you are done with installation!
patching file src/reflect/value.go
Hunk #1 succeeded at 754 (offset 3 lines).
patching file targets/wasi.json
Hunk #2 succeeded at 10 with fuzz 1.
Create your first Contract!
It is recommended that you create your first project using our template.
$ fvm_go_sdk new -- <YOUR_ACTOR_NAME>
fvm_go_sdk will generate the following scaffolding for you.
.
├── README.md
├── actor
│ ├── actor.go # Write your contract here
│ └── cbor_gen.go
├── client
│ └── client.go # client for installation and deployment of the contract
├── entry.go # Main entry point of the contract. If you change interfaces of your actor, please build again to renew the entry point file
├── gen
│ ├── go.mod
│ ├── go.sum
│ └── main.go
├── go.mod
├── go.sum
├── <YOUR_ACTOR_NAME>.wasm # WASM contract compiled from actor.go
└── test.json
Compile your contract. And you now have your very first contract ready to be depolyed!
$ fvm_go_sdk build
Deploy your Contract
Follow this instruction to setup local devnet with fvm branch experimental/fvm-m2.
Install actor.
$ lotus chain install-actor <path-to-wasm-bytecode>
Instantiate actor.
$ lotus chain create-actor <code-cid> <encoded-params>
Invoke actor.
$ lotus chain invoke <address> <method_num>
Tips
- Do not use ASM code.
- Avoid using the reflect library. If you have to, make sure that
TinyGosupports it. - Use
go listcommand to check actor dependency issue.
$ go list -json -deps > deps.json
Directories
¶
| Path | Synopsis |
|---|---|
|
gen
module
|
|
|
Package sdk : a go-fvm-sdk for creation actors.
|
Package sdk : a go-fvm-sdk for creation actors. |
|
adt
Package adt provides amt array and map for contract to store something big, avoid to load big data most code move from https://github.com/filecoin-project/specs-actors/tree/master/actors/util/adt
|
Package adt provides amt array and map for contract to store something big, avoid to load big data most code move from https://github.com/filecoin-project/specs-actors/tree/master/actors/util/adt |
|
ferrors
Package ferrors fvm errors
|
Package ferrors fvm errors |
|
frc42dispatch
Package frc42dispatch implement frc42 reference https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0042.md
|
Package frc42dispatch implement frc42 reference https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0042.md |
|
internal
Package internal definite type/function for both sys and sdk
|
Package internal definite type/function for both sys and sdk |
|
sys
Package sys is used to interact with fvm and in this package non-fvm file used to index for ide, this can be convenient for development file with _call suffix defines the wasm export function file with _simulate used to simulate system call, useful for actor unit test others file was wrap for _call file, make the type and style more closely match the standard of go
|
Package sys is used to interact with fvm and in this package non-fvm file used to index for ide, this can be convenient for development file with _call suffix defines the wasm export function file with _simulate used to simulate system call, useful for actor unit test others file was wrap for _call file, make the type and style more closely match the standard of go |
|
sys/simulated
Package simulated is simulated of fvm
|
Package simulated is simulated of fvm |
|
types
Package types go-fvm-sdk types
|
Package types go-fvm-sdk types |