package gsrpc
import "github.com/centrifuge/go-substrate-rpc-client/v4"
Package gsrpc (Go Substrate RPC Client) provides APIs and types around Polkadot and any Substrate-based chain RPC calls. This client is modelled after polkadot-js/api(https://github.com/polkadot-js/api).
Calling RPC methods
Simply instantiate the gsrpc with a URL of your choice, e. g.
api, err := gsrpc.NewSubstrateAPI("wss://poc3-rpc.polkadot.io")
and run any of the provided RPC methods from the api:
hash, err := api.RPC.Chain.GetBlockHashLatest()
Further examples can be found below.
Signing extrinsics
In order to sign extrinsics, you need to have [subkey](https://github.com/paritytech/substrate/tree/master/subkey) installed. Please make sure that you use subkey in the version of your relay chain.
Types
The package [types](https://godoc.org/github.com/centrifuge/go-substrate-rpc-client/v4/types/) exports a number of useful basic types including functions for encoding and decoding them.
To use your own custom types, you can simply create structs and arrays composing those basic types. Here are some examples using composition of a mix of these basic and builtin Go types:
1. Vectors, lists, series, sets, arrays, slices: https://godoc.org/github.com/centrifuge/go-substrate-rpc-client/v4/types/#example_Vec_simple
2. Structs: https://godoc.org/github.com/centrifuge/go-substrate-rpc-client/v4/types/#example_Struct_simple
There are some caveats though that you should be aware of:
1. The order of the values in your structs is of relevance to the encoding. The scale codec Substrate/Polkadot uses does not encode labels/keys.
2. Some types do not have corresponding types in Go. Working with them requires a custom struct with Encoding/Decoding methods that implement the Encodeable/Decodeable interfaces. Examples for that are enums, tuples and vectors with any types, you can find reference implementations of those here: types/enum_test.go , types/tuple_test.go and types/vec_any_test.go
For more information about the types sub-package, see https://godoc.org/github.com/centrifuge/go-substrate-rpc-client/v4/types
Code:play
Code:play
Code:play
Code:play
Output: Code:play
Output: Code:play
Code:play
Example (DisplaySystemEvents)¶
package main
import (
"fmt"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
"github.com/centrifuge/go-substrate-rpc-client/v4/types"
"github.com/centrifuge/go-substrate-rpc-client/v4/types/codec"
)
func main() {
// Query the system events and extract information from them. This example runs until exited via Ctrl-C
// Create our API with a default connection to the local node
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
meta, err := api.RPC.State.GetMetadataLatest()
if err != nil {
panic(err)
}
// Subscribe to system events via storage
key, err := types.CreateStorageKey(meta, "System", "Events", nil)
if err != nil {
panic(err)
}
sub, err := api.RPC.State.SubscribeStorageRaw([]types.StorageKey{key})
if err != nil {
panic(err)
}
defer sub.Unsubscribe()
// outer for loop for subscription notifications
for {
set := <-sub.Chan()
// inner loop for the changes within one of those notifications
for _, chng := range set.Changes {
if !codec.Eq(chng.StorageKey, key) || !chng.HasStorageData {
// skip, we are only interested in events with content
continue
}
// Decode the event records
events := types.EventRecords{}
err = types.EventRecordsRaw(chng.StorageData).DecodeEventRecords(meta, &events)
if err != nil {
panic(err)
}
// Show what we are busy with
for _, e := range events.Balances_Endowed {
fmt.Printf("\tBalances:Endowed:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x, %v\n", e.Who, e.Balance)
}
for _, e := range events.Balances_DustLost {
fmt.Printf("\tBalances:DustLost:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x, %v\n", e.Who, e.Balance)
}
for _, e := range events.Balances_Transfer {
fmt.Printf("\tBalances:Transfer:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v, %v, %v\n", e.From, e.To, e.Value)
}
for _, e := range events.Balances_BalanceSet {
fmt.Printf("\tBalances:BalanceSet:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v, %v, %v\n", e.Who, e.Free, e.Reserved)
}
for _, e := range events.Balances_Deposit {
fmt.Printf("\tBalances:Deposit:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v, %v\n", e.Who, e.Balance)
}
for _, e := range events.Grandpa_NewAuthorities {
fmt.Printf("\tGrandpa:NewAuthorities:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.NewAuthorities)
}
for _, e := range events.Grandpa_Paused {
fmt.Printf("\tGrandpa:Paused:: (phase=%#v)\n", e.Phase)
}
for _, e := range events.Grandpa_Resumed {
fmt.Printf("\tGrandpa:Resumed:: (phase=%#v)\n", e.Phase)
}
for _, e := range events.ImOnline_HeartbeatReceived {
fmt.Printf("\tImOnline:HeartbeatReceived:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x\n", e.AuthorityID)
}
for _, e := range events.ImOnline_AllGood {
fmt.Printf("\tImOnline:AllGood:: (phase=%#v)\n", e.Phase)
}
for _, e := range events.ImOnline_SomeOffline {
fmt.Printf("\tImOnline:SomeOffline:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.IdentificationTuples)
}
for _, e := range events.Indices_IndexAssigned {
fmt.Printf("\tIndices:IndexAssigned:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x%v\n", e.AccountID, e.AccountIndex)
}
for _, e := range events.Indices_IndexFreed {
fmt.Printf("\tIndices:IndexFreed:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.AccountIndex)
}
for _, e := range events.Offences_Offence {
fmt.Printf("\tOffences:Offence:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v%v\n", e.Kind, e.OpaqueTimeSlot)
}
for _, e := range events.Session_NewSession {
fmt.Printf("\tSession:NewSession:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.SessionIndex)
}
for _, e := range events.Staking_Rewarded {
fmt.Printf("\tStaking:Reward:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.Amount)
}
for _, e := range events.Staking_Slashed {
fmt.Printf("\tStaking:Slash:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x%v\n", e.AccountID, e.Balance)
}
for _, e := range events.Staking_OldSlashingReportDiscarded {
fmt.Printf("\tStaking:OldSlashingReportDiscarded:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.SessionIndex)
}
for _, e := range events.System_ExtrinsicSuccess {
fmt.Printf("\tSystem:ExtrinsicSuccess:: (phase=%#v)\n", e.Phase)
}
for _, e := range events.System_ExtrinsicFailed {
fmt.Printf("\tSystem:ExtrinsicFailed:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%v\n", e.DispatchError)
}
for _, e := range events.System_CodeUpdated {
fmt.Printf("\tSystem:CodeUpdated:: (phase=%#v)\n", e.Phase)
}
for _, e := range events.System_NewAccount {
fmt.Printf("\tSystem:NewAccount:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#x\n", e.Who)
}
for _, e := range events.System_KilledAccount {
fmt.Printf("\tSystem:KilledAccount:: (phase=%#v)\n", e.Phase)
fmt.Printf("\t\t%#X\n", e.Who)
}
}
}
}
Example (ListenToBalanceChange)¶
package main
import (
"fmt"
"math/big"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
"github.com/centrifuge/go-substrate-rpc-client/v4/signature"
"github.com/centrifuge/go-substrate-rpc-client/v4/types"
"github.com/centrifuge/go-substrate-rpc-client/v4/types/codec"
)
func main() {
// This example shows how to instantiate a Substrate API and use it to connect to a node and retrieve balance
// updates
//
// NOTE: The example runs until you stop it with CTRL+C
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
meta, err := api.RPC.State.GetMetadataLatest()
if err != nil {
panic(err)
}
alice := signature.TestKeyringPairAlice.PublicKey
key, err := types.CreateStorageKey(meta, "System", "Account", alice)
if err != nil {
panic(err)
}
var accountInfo types.AccountInfo
ok, err := api.RPC.State.GetStorageLatest(key, &accountInfo)
if err != nil || !ok {
panic(err)
}
previous := accountInfo.Data.Free
fmt.Printf("%#x has a balance of %v\n", alice, previous)
fmt.Printf("You may leave this example running and transfer any value to %#x\n", alice)
// Here we subscribe to any balance changes
sub, err := api.RPC.State.SubscribeStorageRaw([]types.StorageKey{key})
if err != nil {
panic(err)
}
defer sub.Unsubscribe()
// outer for loop for subscription notifications
for {
// inner loop for the changes within one of those notifications
for _, chng := range (<-sub.Chan()).Changes {
if !chng.HasStorageData {
continue
}
var acc types.AccountInfo
if err = codec.Decode(chng.StorageData, &acc); err != nil {
panic(err)
}
// Calculate the delta
current := acc.Data.Free
var change = types.U128{Int: big.NewInt(0).Sub(current.Int, previous.Int)}
// Only display positive value changes (Since we are pulling `previous` above already,
// the initial balance change will also be zero)
if change.Cmp(big.NewInt(0)) != 0 {
fmt.Printf("New balance change of: %v %v %v\n", change, previous, current)
previous = current
return
}
}
}
}
Example (ListenToNewBlocks)¶
package main
import (
"fmt"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
)
func main() {
// This example shows how to subscribe to new blocks.
//
// It displays the block number every time a new block is seen by the node you are connected to.
//
// NOTE: The example runs until 10 blocks are received or until you stop it with CTRL+C
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
sub, err := api.RPC.Chain.SubscribeNewHeads()
if err != nil {
panic(err)
}
defer sub.Unsubscribe()
count := 0
for {
head := <-sub.Chan()
fmt.Printf("Chain is at block: #%v\n", head.Number)
count++
if count == 10 {
sub.Unsubscribe()
break
}
}
}
Example (MakeASimpleTransfer)¶
package main
import (
"fmt"
"math/big"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
"github.com/centrifuge/go-substrate-rpc-client/v4/signature"
"github.com/centrifuge/go-substrate-rpc-client/v4/types"
)
func main() {
// This sample shows how to create a transaction to make a transfer from one an account to another.
// Instantiate the API
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
meta, err := api.RPC.State.GetMetadataLatest()
if err != nil {
panic(err)
}
// Create a call, transferring 12345 units to Bob
bob, err := types.NewMultiAddressFromHexAccountID("0x8eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48")
if err != nil {
panic(err)
}
// 1 unit of transfer
bal, ok := new(big.Int).SetString("100000000000000", 10)
if !ok {
panic(fmt.Errorf("failed to convert balance"))
}
c, err := types.NewCall(meta, "Balances.transfer", bob, types.NewUCompact(bal))
if err != nil {
panic(err)
}
// Create the extrinsic
ext := types.NewExtrinsic(c)
genesisHash, err := api.RPC.Chain.GetBlockHash(0)
if err != nil {
panic(err)
}
rv, err := api.RPC.State.GetRuntimeVersionLatest()
if err != nil {
panic(err)
}
key, err := types.CreateStorageKey(meta, "System", "Account", signature.TestKeyringPairAlice.PublicKey)
if err != nil {
panic(err)
}
var accountInfo types.AccountInfo
ok, err = api.RPC.State.GetStorageLatest(key, &accountInfo)
if err != nil || !ok {
panic(err)
}
nonce := uint32(accountInfo.Nonce)
o := types.SignatureOptions{
BlockHash: genesisHash,
Era: types.ExtrinsicEra{IsMortalEra: false},
GenesisHash: genesisHash,
Nonce: types.NewUCompactFromUInt(uint64(nonce)),
SpecVersion: rv.SpecVersion,
Tip: types.NewUCompactFromUInt(100),
TransactionVersion: rv.TransactionVersion,
}
// Sign the transaction using Alice's default account
err = ext.Sign(signature.TestKeyringPairAlice, o)
if err != nil {
panic(err)
}
// Send the extrinsic
_, err = api.RPC.Author.SubmitExtrinsic(ext)
if err != nil {
panic(err)
}
fmt.Printf("Balance transferred from Alice to Bob: %v\n", bal.String())
}
Balance transferred from Alice to Bob: 100000000000000
Example (SimpleConnect)¶
package main
import (
"fmt"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
)
func main() {
// The following example shows how to instantiate a Substrate API and use it to connect to a node
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
chain, err := api.RPC.System.Chain()
if err != nil {
panic(err)
}
nodeName, err := api.RPC.System.Name()
if err != nil {
panic(err)
}
nodeVersion, err := api.RPC.System.Version()
if err != nil {
panic(err)
}
fmt.Printf("You are connected to chain %v using %v v%v\n", chain, nodeName, nodeVersion)
}
You are connected to chain Development using Parity Polkadot v0.9.43-ba42b9ce51d
Example (TransactionWithEvents)¶
package main
import (
"fmt"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
"github.com/centrifuge/go-substrate-rpc-client/v4/signature"
"github.com/centrifuge/go-substrate-rpc-client/v4/types"
)
func main() {
// Display the events that occur during a transfer by sending a value to bob
// Instantiate the API
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
meta, err := api.RPC.State.GetMetadataLatest()
if err != nil {
panic(err)
}
// Create a call, transferring 12345 units to Bob
bob, err := types.NewAddressFromHexAccountID("0x8eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48")
if err != nil {
panic(err)
}
amount := types.NewUCompactFromUInt(12345)
c, err := types.NewCall(meta, "Balances.transfer", bob, amount)
if err != nil {
panic(err)
}
// Create the extrinsic
ext := types.NewExtrinsic(c)
genesisHash, err := api.RPC.Chain.GetBlockHash(0)
if err != nil {
panic(err)
}
rv, err := api.RPC.State.GetRuntimeVersionLatest()
if err != nil {
panic(err)
}
// Get the nonce for Alice
key, err := types.CreateStorageKey(meta, "System", "Account", signature.TestKeyringPairAlice.PublicKey)
if err != nil {
panic(err)
}
var accountInfo types.AccountInfo
ok, err := api.RPC.State.GetStorageLatest(key, &accountInfo)
if err != nil || !ok {
panic(err)
}
nonce := uint32(accountInfo.Nonce)
o := types.SignatureOptions{
BlockHash: genesisHash,
Era: types.ExtrinsicEra{IsMortalEra: false},
GenesisHash: genesisHash,
Nonce: types.NewUCompactFromUInt(uint64(nonce)),
SpecVersion: rv.SpecVersion,
Tip: types.NewUCompactFromUInt(0),
TransactionVersion: rv.TransactionVersion,
}
fmt.Printf("Sending %v from %#x to %#x with nonce %v", amount, signature.TestKeyringPairAlice.PublicKey, bob.AsAccountID, nonce)
// Sign the transaction using Alice's default account
err = ext.Sign(signature.TestKeyringPairAlice, o)
if err != nil {
panic(err)
}
// Do the transfer and track the actual status
sub, err := api.RPC.Author.SubmitAndWatchExtrinsic(ext)
if err != nil {
panic(err)
}
defer sub.Unsubscribe()
for {
status := <-sub.Chan()
fmt.Printf("Transaction status: %#v\n", status)
if status.IsInBlock {
fmt.Printf("Completed at block hash: %#x\n", status.AsInBlock)
return
}
}
}
Example (UnsubscribeFromListeningToUpdates)¶
package main
import (
"fmt"
"time"
gsrpc "github.com/centrifuge/go-substrate-rpc-client/v4"
"github.com/centrifuge/go-substrate-rpc-client/v4/config"
)
func main() {
// This example shows how to subscribe to and later unsubscribe from listening to block updates.
//
// In this example we're calling the built-in unsubscribe() function after a timeOut of 20s to cleanup and
// unsubscribe from listening to updates.
api, err := gsrpc.NewSubstrateAPI(config.Default().RPCURL)
if err != nil {
panic(err)
}
sub, err := api.RPC.Chain.SubscribeNewHeads()
if err != nil {
panic(err)
}
defer sub.Unsubscribe()
timeout := time.After(20 * time.Second)
for {
select {
case head := <-sub.Chan():
fmt.Printf("Chain is at block: #%v\n", head.Number)
case <-timeout:
sub.Unsubscribe()
fmt.Println("Unsubscribed")
return
}
}
}
Index ¶
Examples ¶
- package (DisplaySystemEvents)
- package (ListenToBalanceChange)
- package (ListenToNewBlocks)
- package (MakeASimpleTransfer)
- package (SimpleConnect)
- package (TransactionWithEvents)
- package (UnsubscribeFromListeningToUpdates)
Types ¶
type SubstrateAPI ¶
func NewSubstrateAPI ¶
func NewSubstrateAPI(url string) (*SubstrateAPI, error)
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
client | |
client/mocks | |
config | |
error | |
gethrpc | Package rpc implements bi-directional JSON-RPC 2.0 on multiple transports. |
hash | |
registry | |
registry/exec | |
registry/parser | |
registry/retriever | |
registry/state | |
registry/test | |
rpc | |
rpc/author | |
rpc/author/mocks | |
rpc/beefy | |
rpc/beefy/mocks | |
rpc/chain | |
rpc/chain/generic | |
rpc/chain/mocks | |
rpc/mmr | |
rpc/mmr/mocks | |
rpcmocksrv | |
rpc/offchain | |
rpc/offchain/mocks | |
rpc/state | |
rpc/state/mocks | |
rpc/system | |
rpc/system/mocks | |
scale | |
signature | |
teste2e | |
types | |
types/codec | |
types/test | |
types/test/test-gen | |
types/test_utils | |
xxhash |
- Version
- v4.2.1 (latest)
- Published
- Dec 5, 2023
- Platform
- linux/amd64
- Imports
- 2 packages
- Last checked
- 1 week ago –
Tools for package owners.