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.
candid		A Candid library for Golang.
certificate		A Certification library for Golang.
gen		A library to generate Golang clients.
ic		Multiple auto-generated sub-modules to talk to the Internet Computer services
identity		A library that creates/manages identities.
principal		Generic Identifiers for the Internet Computer

More dependencies in the go.mod file.

Documentation

Overview

Example (Anonymous_query)

ledgerID, _ := principal.Decode("ryjl3-tyaaa-aaaaa-aaaba-cai")
a, _ := agent.New(agent.Config{})
args, err := candid.EncodeValueString("record { account = \"9523dc824aa062dcd9c91b98f4594ff9c6af661ac96747daef2090b7fe87037d\" }")
if err != nil {
	fmt.Println(err)
}
fmt.Println(a.QueryString(ledgerID, "account_balance_dfx", args))

Output:

(record { 5035232 = 0 : nat64 }) <nil>

Example (Query)

publicKey, privateKey, _ := ed25519.GenerateKey(rand.Reader)
id, _ := identity.NewEd25519Identity(publicKey, privateKey)
ledgerID, _ := principal.Decode("ryjl3-tyaaa-aaaaa-aaaba-cai")
a, _ := agent.New(agent.Config{
	Identity: id,
})
args, err := candid.EncodeValueString("record { account = \"9523dc824aa062dcd9c91b98f4594ff9c6af661ac96747daef2090b7fe87037d\" }")
if err != nil {
	fmt.Println(err)
}
fmt.Println(a.QueryString(ledgerID, "account_balance_dfx", args))

Output:

(record { 5035232 = 0 : nat64 }) <nil>

Index

• type Agent
  • func New(cfg Config) (*Agent, error)
  • func (a Agent) Call(canisterID principal.Principal, methodName string, args []byte, values []any) error
  • func (a Agent) CallCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)
  • func (a Agent) CallRaw(canisterID principal.Principal, methodName string, args []byte) ([]byte, error)
  • func (a Agent) CallString(canisterID principal.Principal, methodName string, args []byte) (string, 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, values []any) error
  • func (a Agent) QueryCandid(canisterID principal.Principal, methodName string, args []byte) ([]idl.Type, []interface{}, error)
  • func (a Agent) QueryRaw(canisterID principal.Principal, methodName string, args []byte) ([]byte, error)
  • func (a Agent) QueryString(canisterID principal.Principal, methodName string, args []byte) (string, error)
  • func (a Agent) RequestStatus(canisterID principal.Principal, requestID RequestID) ([]byte, certificate.Node, error)
  • func (a Agent) Sender() principal.Principal
• type Client
  • func NewClient(cfg ClientConfig) Client
  • func (c Client) Status() (*Status, error)
• type ClientConfig
• type Config
• type Envelope
• type Implementation
• type Request
  • func (r *Request) MarshalCBOR() ([]byte, error)
  • func (r *Request) UnmarshalCBOR(data []byte) 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) MarshalCBOR() ([]byte, error)
  • func (s *Status) UnmarshalCBOR(data []byte) error

Examples

• Package (Anonymous_query)
• Package (Query)
• Client.Status

Types

type Agent

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

Agent is a client for the Internet Computer.

func New

func New(cfg Config) (*Agent, error)

New returns a new Agent based on the given configuration.

func (Agent) Call

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

Call calls a method on a canister and unmarshals the result into the given values.

func (Agent) CallCandid

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

CallCandid calls a method on a canister and returns the raw Candid result as a list of types and values.

func (Agent) CallRaw

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

CallRaw calls a method on a canister and returns the raw Candid result.

func (Agent) CallString

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

CallString calls a method on a canister and returns the result as a string.

func (Agent) GetCanisterControllers

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

GetCanisterControllers returns the list of principals that can control the given canister.

func (Agent) GetCanisterInfo

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

GetCanisterInfo returns the raw certificate for the given canister based on the given sub-path.

func (Agent) GetCanisterModuleHash

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

GetCanisterModuleHash returns the module hash for the given canister.

func (Agent) Query

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

Query queries a method on a canister and unmarshals the result into the given values.

func (Agent) QueryCandid

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

QueryCandid queries a method on a canister and returns the raw Candid result as a list of types and values.

func (Agent) QueryRaw

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

QueryRaw queries a method on a canister and returns the raw Candid result.

func (Agent) QueryString

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

QueryString queries a method on a canister and returns the result as a string.

func (Agent) RequestStatus

func (a Agent) RequestStatus(canisterID principal.Principal, requestID RequestID) ([]byte, certificate.Node, error)

RequestStatus returns the status of the request with the given ID.

func (Agent) Sender

func (a Agent) Sender() principal.Principal

Sender returns the principal that is sending the requests.

type Client

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

Client is a client for the IC agent.

func NewClient

func NewClient(cfg ClientConfig) Client

NewClient creates a new client based on the given configuration.

func (Client) Status

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

Status returns the status of the IC.

Example

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

Output:

0.18.0

type ClientConfig

type ClientConfig struct {
	Host *url.URL
}

ClientConfig is the configuration for a client.

type Config

type Config struct {
	Identity      identity.Identity
	IngressExpiry time.Duration
	ClientConfig  *ClientConfig
	FetchRootKey  bool
}

Config is the configuration for an Agent.

type Envelope

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

Envelope is a wrapper for a Request that includes the sender's public key and signature.

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 {
	// The type of the request. This is used to distinguish between query, call and read_state requests.
	Type RequestType
	// The user who issued the request.
	Sender principal.Principal
	// Arbitrary user-provided data, typically randomly generated. This can be
	// used to create distinct requests with otherwise identical fields.
	Nonce []byte
	// An upper limit on the validity of the request, expressed in nanoseconds
	// since 1970-01-01 (like ic0.time()).
	IngressExpiry uint64
	// The principal of the canister to call.
	CanisterID principal.Principal
	// Name of the canister method to call.
	MethodName string
	// Argument to pass to the canister method.
	Arguments []byte
	// A list of paths, where a path is itself a sequence of blobs.
	Paths [][][]byte
}

Request is the request to the agent. DOCS: https://smartcontracts.org/docs/interface-spec/index.html#http-call

func (*Request) MarshalCBOR

func (r *Request) MarshalCBOR() ([]byte, error)

MarshalCBOR implements the CBOR marshaler interface.

func (*Request) UnmarshalCBOR

func (r *Request) UnmarshalCBOR(data []byte) error

UnmarshalCBOR implements the CBOR unmarshaler interface.

type RequestID

type RequestID [32]byte

RequestID is the request ID.

func NewRequestID

func NewRequestID(req Request) RequestID

NewRequestID creates a new request ID. DOCS: https://smartcontracts.org/docs/interface-spec/index.html#request-id

func (RequestID) Sign

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

Sign signs the request ID with the given identity.

type RequestType

type RequestType = string

RequestType is the type of request.

const (
	// RequestTypeCall is a call request.
	RequestTypeCall RequestType = "call"
	// RequestTypeQuery is a query request.
	RequestTypeQuery RequestType = "query"
	// RequestTypeReadState is a read state request.
	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"`
}

Response is the response from the agent.

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) MarshalCBOR

func (s *Status) MarshalCBOR() ([]byte, error)

func (*Status) UnmarshalCBOR

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

UnmarshalCBOR implements the CBOR unmarshaler interface.