Go Agent for the Internet Computer

go get github.com/aviate-labs/agent-go

Getting Started

The agent is a library that allows you to talk to the Internet Computer.

package main

import (
	"github.com/aviate-labs/agent-go"
	"github.com/aviate-labs/agent-go/ic"
	"log"
)

type (
	Account struct {
		Account string `ic:"account"`
	}

	Balance struct {
		E8S uint64 `ic:"e8s"`
	}
)

func main() {
	a, _ := agent.New(agent.DefaultConfig)

	var balance Balance
	if err := a.Query(
		principal.MustDecode("ryjl3-tyaaa-aaaaa-aaaba-cai"), "account_balance_dfx",
		[]any{Account{"9523dc824aa062dcd9c91b98f4594ff9c6af661ac96747daef2090b7fe87037d"}},
		[]any{&balance},
	); err != nil {
		log.Fatal(err)
	}

	_ = balance // Balance{E8S: 0}
}

Using an Identity

Supported identities are Ed25519 and Secp256k1. By default, the agent uses the anonymous identity.

id, _ := identity.NewEd25519Identity(publicKey, privateKey)
config := agent.Config{
    Identity: id,
}

Using the Local Replica

If you are running a local replica, you can use the FetchRootKey option to fetch the root key from the replica.

u, _ := url.Parse("http://localhost:8000")
config := agent.Config{
    ClientConfig: &agent.ClientConfig{Host: u},
    FetchRootKey: true,
    DisableSignedQueryVerification: true,
}

Packages

You can find the documentation for each package in the links below. Examples can be found throughout the documentation.

Package Name	Links	Description
agent		A library to talk directly to the Replica.
candid		A Candid library for Golang.
certification		A Certification library for Golang.
gen		A library to generate Golang clients.
identity		A library that creates/manages identities.
pocketic-go		A client library to talk to the PocketIC Server.
principal		Generic Identifiers for the Internet Computer
registry		A client to interact with the registry canister.
-----------------	-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	-------------------------------------------------------------------------------
ic-go		Multiple auto-generated sub-modules to talk to the Internet Computer services
pocketic-go		A client library to talk to the PocketIC Server.

More dependencies in the go.mod file.

CLI

go install github.com/aviate-labs/agent-go/cmd/goic@latest

Read more here

Testing

This repository contains two types of tests: standard Go tests and PocketIC -dependent tests. The test suite runs a local PocketIC server using the installed pocket-ic-server to execute some end-to-end (e2e) tests. If pocket-ic-server is not installed, those specific tests will be skipped.

go test -v ./...

Reference Implementations

• Rust Agent
• JavaScript Agent