agent

README

Go Agent for the Internet Computer

Testing

There are two types of tests within this repository; the normal go tests and DFX dependent tests. The test suite will run a local replica through DFX to run some e2e tests. If you do not have it installed then those tests will be ignored.

go test -v ./...

Packages

Package Name	Links	Description
agent		A library to talk directly to the Replica.
identity		A library that creates/manages identities.

Dependencies

Package Name	Links	Description
candid		A Candid library for Golang
principal		Generic Identifiers for the Internet Computer

More dependencies in the go.mod file.

Documentation

Index

• type Agent
  • func New(cfg AgentConfig) Agent
  • func (a Agent) Call(canisterID principal.Principal, methodName string, args []byte) (string, error)
  • func (a Agent) CallCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)
  • func (a Agent) GetCanisterControllers(canisterID principal.Principal) ([]principal.Principal, error)
  • func (a Agent) GetCanisterInfo(canisterID principal.Principal, subPath string) ([]byte, error)
  • func (a Agent) GetCanisterModuleHash(canisterID principal.Principal) ([]byte, error)
  • func (a Agent) Query(canisterID principal.Principal, methodName string, args []byte) (string, error)
  • func (a Agent) QueryCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)
  • func (agent *Agent) RequestStatus(canisterID principal.Principal, requestID RequestID) ([]byte, cert.Node, error)
  • func (a Agent) Sender() principal.Principal
• type AgentConfig
• type Client
  • func NewClient(cfg ClientConfig) Client
  • func (c Client) Status() (Status, error)
• type ClientConfig
• type Envelope
• type Implementation
• type Request
  • func NewRequest(sender principal.Principal, requestType RequestType, ...) (Request, error)
• type RequestID
  • func NewRequestID(req Request) RequestID
  • func (r RequestID) Sign(id identity.Identity) []byte
• type RequestType
• type Response
• type Status
  • func (s *Status) UnmarshalCBOR(data []byte) error

Examples

• Client.Status

Types

type Agent

type Agent struct {
	// contains filtered or unexported fields
}

func New

func New(cfg AgentConfig) Agent

func (Agent) Call

func (a Agent) Call(canisterID principal.Principal, methodName string, args []byte) (string, error)

func (Agent) CallCandid

func (a Agent) CallCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)

func (Agent) GetCanisterControllers

func (a Agent) GetCanisterControllers(canisterID principal.Principal) ([]principal.Principal, error)

func (Agent) GetCanisterInfo

func (a Agent) GetCanisterInfo(canisterID principal.Principal, subPath string) ([]byte, error)

func (Agent) GetCanisterModuleHash

func (a Agent) GetCanisterModuleHash(canisterID principal.Principal) ([]byte, error)

func (Agent) Query

func (a Agent) Query(canisterID principal.Principal, methodName string, args []byte) (string, error)

func (Agent) QueryCandid

func (a Agent) QueryCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)

func (*Agent) RequestStatus

func (agent *Agent) RequestStatus(canisterID principal.Principal, requestID RequestID) ([]byte, cert.Node, error)

func (Agent) Sender

func (a Agent) Sender() principal.Principal

type AgentConfig

type AgentConfig struct {
	Identity      *identity.Identity
	IngressExpiry time.Duration
	ClientConfig  *ClientConfig
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(cfg ClientConfig) Client

func (Client) Status

func (c Client) Status() (Status, error)

Example

package main

import (
	"fmt"
	"net/url"

	"github.com/aviate-labs/agent-go"
)

var ic0, _ = url.Parse("https://ic0.app/")

func main() {
	c := agent.NewClient(agent.ClientConfig{ic0})
	status, _ := c.Status()
	fmt.Println(status.Version)
}

Output:
0.18.0

type ClientConfig

type ClientConfig struct {
	Host *url.URL
}

type Envelope

type Envelope struct {
	Content      Request `cbor:"content,omitempty"`
	SenderPubkey []byte  `cbor:"sender_pubkey,omitempty"`
	SenderSig    []byte  `cbor:"sender_sig,omitempty"`
}

type Implementation

type Implementation struct {
	// Source is the canonical location of the source code.
	Source string
	// Version is the version number of the implementation.
	Version string
	// Revision is the precise git revision of the implementation.
	Revision string
}

Implementation identifies the implementation of the Internet Computer.

type Request

type Request struct {
	Type RequestType `cbor:"request_type"`
	// The user who issued the request.
	Sender principal.Principal `cbor:"sender"`
	// Arbitrary user-provided data, typically randomly generated. This can be
	// used to create distinct requests with otherwise identical fields.
	Nonce []byte `cbor:"nonce"`
	// An upper limit on the validity of the request, expressed in nanoseconds
	// since 1970-01-01 (like ic0.time()).
	IngressExpiry uint64 `cbor:"ingress_expiry"`
	// The principal of the canister to call.
	CanisterID principal.Principal `cbor:"canister_id"`
	// Name of the canister method to call.
	MethodName string `cbor:"method_name"`
	// Argument to pass to the canister method.
	Arguments []byte `cbor:"arg"`
	// A list of paths, where a path is itself a sequence of blobs.
	Paths [][][]byte `cbor:"paths,omitempty"`
}

DOCS: https://smartcontracts.org/docs/interface-spec/index.html#http-call

func NewRequest

func NewRequest(
	sender principal.Principal,
	requestType RequestType,
	canisterID principal.Principal,
	methodName string,
	arguments string,
	effective uint64,
) (Request, error)

type RequestID

type RequestID [32]byte

func NewRequestID

func NewRequestID(req Request) RequestID

DOCS: https://smartcontracts.org/docs/interface-spec/index.html#request-id

func (RequestID) Sign

func (r RequestID) Sign(id identity.Identity) []byte

type RequestType

type RequestType = string

const (
	RequestTypeCall      RequestType = "call"
	RequestTypeQuery     RequestType = "query"
	RequestTypeReadState RequestType = "read_state"
)

type Response

type Response struct {
	Status     string            `cbor:"status"`
	Reply      map[string][]byte `cbor:"reply"`
	RejectCode uint64            `cbor:"reject_code"`
	RejectMsg  string            `cbor:"reject_message"`
}

type Status

type Status struct {
	// Identifies the interface version supported.
	Version string
	// Impl describes the implementation of the Internet Computer.
	Impl *Implementation
	// The public key (a DER-encoded BLS key) of the root key of this Internet Computer instance.
	RootKey []byte
}

Status describes various status fields of the Internet Computer.

func (*Status) UnmarshalCBOR

func (s *Status) UnmarshalCBOR(data []byte) error