deepsquare

Documentation

Overview

Package deepsquare provides a all-in-one Client that implements all of the DeepSquare services.

See more examples: https://github.com/deepsquare-io/grid/tree/main/_examples

Initializing the clients

There are two types of client: the Client and the Watcher. The Watcher uses WebSockets to monitor events, where the endpoint may be different from the RPC endpoint.

To initialize the client, do:

// Initialize client for simple RPCs
client, err := deepsquare.NewClient(ctx, &deepsquare.ClientConfig{
	MetaschedulerAddress: common.HexToAddress("0x..."),
	RPCEndpoint:          "https://testnet.deepsquare.run/rpc",  // Optional
	SBatchEndpoint:       "https://sbatch.deepsquare.run/graphql",  // Optional
	LoggerEndpoint:       "https://grid-logger.deepsquare.run",  // Optional
	UserPrivateKey:       pk,  // Optional, but needed for authenticated requests
})

To initialize the watcher, do:

// Initialize client for streaming RPCs
watcher, err := deepsquare.NewWatcher(ctx, &deepsquare.WatcherConfig{
	MetaschedulerAddress: common.HexToAddress("0x..."),
	RPCEndpoint:          "https://testnet.deepsquare.run/rpc",  // Optional
	WSEndpoint:           "https://testnet.deepsquare.run/ws",  // Optional
	UserPrivateKey:       pk,  // Optional, but needed for authenticated requests
})
defer watcher.Close()

The private key can be parsed with the `go-ethereum` package:

import (
	"github.com/ethereum/go-ethereum/common"
	"github.com/ethereum/go-ethereum/crypto"
)

// Parse private key
pk, err := crypto.HexToECDSA(ethHexPK)
if err != nil {
	// ...
}

Submitting Jobs

To submit jobs, you need to set the allowance first to allow the meta-scheduler to take you some credits:

lockedCredits, _ := new(big.Int).SetString("100000000000000000000", 10)

// Set allowance
curr, err := client.GetAllowance(ctx)
if err != nil {
	return err
}
if err = client.SetAllowance(ctx, curr.Add(curr, lockedCredits)); err != nil {
	return err
}

You can set a high number to allow auto-topup:

// Set allowance
limit, _ := new(big.Int).SetString("10000000000000000000000000000000000000", 10)
if err = client.SetAllowance(ctx, curr.Add(curr, limit)); err != nil {
	return err
}

The credits will be used to finance the project and the infrastructure providers.

After settings the allowance, you can submit a job:

_, err = client.SubmitJob(
	ctx,
	&sbatch.Job{
		Resources: &sbatch.JobResources{
			Tasks:       1,
			CpusPerTask: 1,
			MemPerCPU:   100,
			GpusPerTask: 0,
		},
		Steps: []*sbatch.Step{
			{
				Run: &sbatch.StepRun{
					Command: "echo test",
				},
			},
		},
	},
	lockedCredits,
	jobName,
)

The object sbatch.Job has `json` and `yaml` tags, so it's possible to unmarshall a JSON object to an sbatch.Job.

Managing Jobs

Get a job:

job, err := client.GetJob(ctx, jobID)

Get your jobs:

jobs, err := client.GetJobs(ctx)
if err != nil {
	log.Fatalln(err.Error())
}

// Iterate
for jobs.Next(ctx) {
	fmt.Println(jobs.Current())
}

// Handle error
if jobs.Error() != nil {
	if err != nil {
		log.Fatalln(err.Error())
	}
}

Top-up a job:

err := client.TopUpJob(ctx, jobID, amount)

Panicking a job (only for admins):

err := client.PanicJob(ctx, jobID, reason)

Managing Allowance

To get, do:

allowance, err := client.GetAllowance(ctx)

To set, do:

err := client.SetAllowance(ctx, amount)

To watch, do:

approvals := make(chan types.Approval, 1)
	sub, err := m.watcher.SubscribeEvents(
		ctx,
		types.FilterApproval(approvals),
	)
	if err != nil {
		// ...
	}
	defer sub.Unsubscribe()

	allowances, err := m.client.ReduceToAllowance(ctx, approvals)

	for {
		select {
		case allowance := <-allowances:
			// Handle allowance

		case err := <-sub.Err():
			// Handle error
		}
	}

Managing Credits

To get, do:

credits, err := client.Balance(ctx)
// Or
credits, err := client.BalanceOf(ctx, address)

To transfer, do:

err := client.Transfer(ctx, address, amount)

To watch, do:

transfers := make(chan types.Transfer, 1)
sub, err := m.watcher.SubscribeEvents(
	ctx,
	types.FilterTransfer(transfers),
)
if err != nil {
	// ...
}
defer sub.Unsubscribe()

balances, err := m.client.ReduceToBalance(ctx, transfers)

for {
	select {
	case balance := <-balances:
		// Handle balance

	case err := <-sub.Err():
		// Handle error
	}
}

Managing Providers (for admins)

To get, do:

provider, err := client.GetProvider(ctx, providerAddress)

To list all providers, do:

providers, err := client.GetProviders(ctx, providerAddress)

To approve, do:

err := client.Approve(ctx, providerAddress)

To remove, do:

err := client.Remove(ctx, providerAddress)

Watching events

To watch the events, the watcher has a `SubscribeEvents` method in which you can pass filters:

transfers := make(chan types.Transfer, 1)
sub, err := m.watcher.SubscribeEvents(
	ctx,
	types.FilterTransfer(transfers),
)
if err != nil {
	// ...
}
defer sub.Unsubscribe()

A thread will be handling the passing of data to the channels.

Call `sub.Unsubscribe()` to stop the subscription, and use `<-sub.Err()` to fetch the error.

Index

• Constants
• type Client
  • func NewClient(ctx context.Context, c *ClientConfig) (Client, error)
• type ClientConfig
• type Watcher
  • func NewWatcher(ctx context.Context, c *WatcherConfig) (Watcher, error)
• type WatcherConfig

Constants

const (
	DefaultRPCEndpoint    = "https://testnet.deepsquare.run/rpc"
	DefaultWSEndpoint     = "wss://testnet.deepsquare.run/ws"
	DefaultSBatchEndpoint = "https://sbatch.deepsquare.run/graphql"
	DefaultLoggerEndpoint = "https://grid-logger.deepsquare.run"
)

Default values for the client.

Types

type Client

type Client interface {
	types.Logger
	types.JobScheduler
	types.JobFetcher
	types.CreditManager
	types.AllowanceManager
	types.ProviderManager
	// Close all connections.
	Close() error
}

Client implements all the services required to make unary calls to DeepSquare APIs.

Users must call Close() at the end of the application to avoid pending connections.

func NewClient

func NewClient(ctx context.Context, c *ClientConfig) (Client, error)

NewClient creates a new Client for the given ClientConfig.

type ClientConfig

type ClientConfig struct {
	http.Client
	// MetaschedulerAddress is the address of the smart-contract.
	MetaschedulerAddress common.Address
	// RPCEndpoint is the URL of the network API of the Ethereum Virtual Machine (EVM). The parameter is optional.
	RPCEndpoint string
	// SBatchEndpoint is the URL of the SBatch service. The parameter is optional.
	SBatchEndpoint string
	// SBatchEndpoint is the URL of the grid logger. The parameter is optional.
	LoggerEndpoint string
	// UserPrivateKey is the ECDSA private key of an ethereum wallet. This permits
	// authenticated requests if specified.
	UserPrivateKey *ecdsa.PrivateKey
	// TLSConfig of the HTTP and WS client used for all the connections. This parameter is optional.
	TLSConfig *tls.Config
}

ClientConfig is used to configure the Client's services.

type Watcher

type Watcher interface {
	types.EventSubscriber
	// Close all connections.
	Close() error
}

Watcher implements all the services required to make streaming calls to DeepSquare APIs.

Users must call Close() at the end of the application to avoid pending connections.

func NewWatcher

func NewWatcher(ctx context.Context, c *WatcherConfig) (Watcher, error)

NewWatcher creates a new Watcher for the given WatcherConfig.

type WatcherConfig

type WatcherConfig struct {
	http.Client
	MetaschedulerAddress common.Address
	RPCEndpoint          string
	WSEndpoint           string
	UserPrivateKey       *ecdsa.PrivateKey
	TLSConfig            *tls.Config
}

WatcherConfig is used to configure the Watcher's services.