service

README

Wallet API

Authentication

Logging in to a wallet

POST api/v1/auth/token

Logging in to a wallet is done using the wallet name and passphrase. The operation fails if the wallet not exist, or if the passphrase used is incorrect. On success, the wallet is loaded, a session is created and a JWT is returned to the user.

Example

Request

{
  "wallet": "your_wallet_name",
  "passphrase": "super-secret"
}

Command

curl -s -XPOST -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/auth/token

Response

{
  "token": "abcd.efgh.ijkl"
}

Logging out from a wallet

DELETE api/v1/auth/token

Using the JWT returned when logging in, the session is recovered and removed from the service. The wallet can no longer be accessed using the token from this point on.

Example

Command

curl -s -XDELETE -H 'Authorization: Bearer abcd.efgh.ijkl' http://127.0.0.1:1789/api/v1/auth/token

Response

{
  "success": true
}

Network management

Get current network configuration

GET api/v1/network

Example

Command

curl -s -XPOST -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/network

Response

{
  "network": {
    "name": "mainnet"
  }
}

Wallet management

Create a wallet

POST api/v1/wallets

Creating a wallet is done using a name and passphrase. If a wallet with the same name already exists, the action is aborted. The new wallets is encrypted (using the passphrase) and saved to a file on the file system. A session and accompanying JWT is created, and the JWT is returned to the user.

Example

Request

{
  "wallet": "your_wallet_name",
  "passphrase": "super-secret"
}

Command

curl -s -XPOST -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/wallets

Response

{
  "token": "abcd.efgh.ijkl"
}

Import a wallet

POST api/v1/wallets/import

Import a wallet is done using a name, a passphrase, and a recoveryPhrase. If a wallet with the same name already exists, the action is aborted. The imported wallet is encrypted (using the passphrase) and saved to a file on the file system. A session and accompanying JWT is created, and the JWT is returned to the user.

Example

Request

{
  "wallet": "your_wallet_name",
  "passphrase": "super-secret",
  "recoveryPhrase": "my twenty four words recovery phrase"
}

Command

curl -s -XPOST -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/wallets

Response

{
  "token": "abcd.efgh.ijkl"
}

Key management

Generate a key pair

POST api/v1/keys

Authentication required.

It generates a new key pair into the logged wallet, and returns the generated public key.

Example

Request

{
  "passphrase": "super-secret",
  "meta": [
    {
      "key": "somekey",
      "value": "somevalue"
    }
  ]
}

Command

curl -s -XPOST -H 'Authorization: Bearer abcd.efgh.ijkl' -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/keys

Response

{
  "key": {
    "pub": "1122aabb",
    "algo": "ed25519",
    "tainted": false,
    "meta": [
      {
        "key": "somekey",
        "value": "somevalue"
      }
    ]
  }
}

List keys

GET api/v1/keys

Authentication required.

Users can list all the public keys (with taint status, and metadata) of the logged wallet.

Example

Command

curl -s -XGET -H "Authorization: Bearer abcd.efgh.ijkl" http://127.0.0.1:1789/api/v1/keys

Response

{
  "keys": [
    {
      "pub": "1122aabb",
      "algo": "ed25519",
      "tainted": false,
      "meta": [
        {
          "key": "somekey",
          "value": "somevalue"
        }
      ]
    }
  ]
}

Describe a key pair

GET api/v1/keys/:keyid

Authentication required.

Return the information associated the public key :keyid, from the logged wallet. The private key is not returned.

Example

Command

  curl -s -XPUT -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789api/v1/keys/1122aabb

Response

{
  "key": {
    "index": 1,
    "pub": "1122aabb"
  }
}

Taint a key pair

PUT api/v1/keys/:keyid/taint

Authentication required.

Taint the key pair matching the public key :keyid, from the logged wallet. The key pair must belong to the logged wallet.

Example

Request

{
  "passphrase": "super-secret"
}

Command

  curl -s -XPUT -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/keys/1122aabb/taint

Response

{
  "success": true
}

Annotate a key pair

PUT api/v1/keys/:keyid/metadata

Authentication required.

Annotating a key pair replace the metadata matching the public key :keyid, from the logged wallet. The key pair must belong to the logged wallet.

Example

Request

{
  "passphrase": "super-secret",
  "meta": [
    {
      "key": "newkey",
      "value": "newvalue"
    }
  ]
}

Command

  curl -s -XPUT -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/keys/1122aabb/metadata

Response

{
  "success": true
}

Commands

Sign a command

POST api/v1/command

Authentication required.

Sign a Vega command using the specified key pair, and returns the signed transaction. The key pair must belong to the logged wallet.

Example

Request

{
  "pubKey": "1122aabb",
  "propagate": true,
  "orderCancellation": {
    "marketId": "YESYESYES"
  }
}

Command

  curl -s -XPOST -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/command

Response

{
  "transaction": {
    "inputData": "dGVzdGRhdG9837420b4b3yb23ybc4o1ui23yEK",
    "signature": {
      "value": "7f6g9sf8f8s76dfa867fda",
      "algo": "vega/ed25519",
      "version": 1
    },
    "from": {
      "pubKey": "1122aabb"
    },
    "version": 1
  }
}

Propagate

In the request payload, when the propagate field can be set to true, the wallet service send the transaction on your behalf to the registered nodes after signing it successfully.

Sign data

POST api/v1/sign

Authentication required.

Sign any base64-encoded data using the specified key pair, and returns the signed transaction. The key pair must belong to the logged wallet.

Example

Request

{
  "inputData": "dGVzdGRhdGEK==",
  "pubKey": "1122aabb"
}

Command

  curl -s -XPOST -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/sign

Response

{
  "hexSignature": "0xhafdsf86df876af",
  "base64Signature": "fad7h34k1jh3g413g=="
}

Verify data

POST api/v1/verify

Verify any base64-encoded data using the specified public key, and returns the confirmation.

Example

Request

{
  "inputData": "dGVzdGRhdGEK==",
  "pubKey": "1122aabb"
}

Command

  curl -s -XPOST -H "Authorization: Bearer abcd.efgh.ijkl" -d 'YOUR_REQUEST' http://127.0.0.1:1789/api/v1/sign

Response

{
  "hexSignature": "0xhafdsf86df876af",
  "base64Signature": "fad7h34k1jh3g413g=="
}

Documentation

Index

• Variables
• func InitialiseService(store Store, overwrite bool) error
• func IsInitialised(store Store) (bool, error)
• func UpdateConfig(store Store, cfg *Config) error
• type APIV1Config
• type APIV2Config
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Validate() error
• type HeaderError
  • func (h HeaderError) Error() string
  • func (h HeaderError) MarshalJSON() ([]byte, error)
  • func (h *HeaderError) UnmarshalJSON(data []byte) error
• type JSONRPCErr
• type LoggerBuilderFunc
• type NetworkStore
• type Nodes
• type ProcessStoppedNotifier
• type ResourceContext
• type ServerConfig
  • func (c ServerConfig) String() string
• type Service
  • func NewService(log *zap.Logger, cfg *Config, apiV1 *v1.API, apiV2 *v2.API) *Service
  • func (s *Service) Start() error
  • func (s *Service) Stop(ctx context.Context) error
• type Starter
  • func NewStarter(walletStore api.WalletStore, netStore api.NetworkStore, svcStore Store, ...) *Starter
  • func (s *Starter) Start(jobRunner *vgjob.Runner, network string, noVersionCheck bool) (_ *ResourceContext, err error)
• type Store

Variables

var (
	ErrInvalidLogLevelValue              = errors.New("the service log level is invalid")
	ErrInvalidMaximumTokenDuration       = errors.New("the maximum token duration is invalid")
	ErrInvalidMaximumNodeRequestDuration = errors.New("the maximum request duration is invalid")
	ErrServerHostUnset                   = errors.New("the service host is unset")
	ErrServerPortUnset                   = errors.New("the service port is unset")
)

var ErrCannotStartMultipleServiceAtTheSameTime = errors.New("cannot start multiple service at the same time")

Functions

func InitialiseService

func InitialiseService(store Store, overwrite bool) error

func IsInitialised

func IsInitialised(store Store) (bool, error)

func UpdateConfig

func UpdateConfig(store Store, cfg *Config) error

Types

type APIV1Config

type APIV1Config struct {
	MaximumTokenDuration vgencoding.Duration `json:"maximumTokenDuration"`
}

type APIV2Config

type APIV2Config struct {
	Nodes Nodes `json:"nodes"`
}

type Config

type Config struct {
	LogLevel vgencoding.LogLevel `json:"logLevel"`
	Server   ServerConfig        `json:"server"`
	APIV1    APIV1Config         `json:"apiV1"`
	APIV2    APIV2Config         `json:"apiV2"`
}

func DefaultConfig

func DefaultConfig() *Config

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the values set in the server config file returning an error is anything is awry.

type HeaderError

type HeaderError struct {
	Key string   `json:"header"`
	Val []string `json:"value"`
}

func (HeaderError) Error

func (h HeaderError) Error() string

func (HeaderError) MarshalJSON

func (h HeaderError) MarshalJSON() ([]byte, error)

func (*HeaderError) UnmarshalJSON

func (h *HeaderError) UnmarshalJSON(data []byte) error

type JSONRPCErr

type JSONRPCErr struct {
	Err     string   `json:"error"`
	Details []string `json:"details,omitempty"`
}

type LoggerBuilderFunc

type LoggerBuilderFunc func(level string) (*zap.Logger, zap.AtomicLevel, error)

LoggerBuilderFunc is used to build a logger. It returns the built logger and a zap.AtomicLevel to allow the caller to dynamically change the log level.

type NetworkStore

type NetworkStore interface {
	NetworkExists(string) (bool, error)
	GetNetwork(string) (*network.Network, error)
}

type Nodes

type Nodes struct {
	MaximumRetryPerRequest uint64              `json:"maximumRetryPerRequest"`
	MaximumRequestDuration vgencoding.Duration `json:"maximumRequestDuration"`
}

type ProcessStoppedNotifier

type ProcessStoppedNotifier func()

type ResourceContext

type ResourceContext struct {
	ServiceURL string
	ErrCh      chan error
}

type ServerConfig

type ServerConfig struct {
	Port int    `json:"port"`
	Host string `json:"host"`
}

func (ServerConfig) String

func (c ServerConfig) String() string

type Service

type Service struct {
	*httprouter.Router
	// contains filtered or unexported fields
}

func NewService

func NewService(log *zap.Logger, cfg *Config, apiV1 *v1.API, apiV2 *v2.API) *Service

func (*Service) Start

func (s *Service) Start() error

func (*Service) Stop

func (s *Service) Stop(ctx context.Context) error

type Starter

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

func NewStarter

func NewStarter(walletStore api.WalletStore, netStore api.NetworkStore, svcStore Store, connectionsManager *connections.Manager, policy servicev1.Policy, interactor api.Interactor, loggerBuilderFunc LoggerBuilderFunc) *Starter

func (*Starter) Start

func (s *Starter) Start(jobRunner *vgjob.Runner, network string, noVersionCheck bool) (_ *ResourceContext, err error)

Start builds the components the service relies on and start it.

Why build certain components only at start up, and not during the build phase?

This is because some components are relying on editable configuration. So, the service must be able to be restarted with an updated configuration. Building these components up front would prevent that. This is particularly true for desktop applications that can edit the configuration and start the service in the same process.

type Store

type Store interface {
	GetRsaKeys() (*v1.RSAKeys, error)
	RSAKeysExists() (bool, error)
	SaveRSAKeys(*v1.RSAKeys) error
	ConfigExists() (bool, error)
	SaveConfig(*Config) error
	GetConfig() (*Config, error)
}