ubiquity-go-client

README

Ubiquity-Go-Client

Ubiquity provides a RESTful and uniform way to access blockchain resources, with a rich and reusable model across multiple cryptocurrencies. See Ubiquity docs

This repo provides a code-generated Go SDK to work with the Ubiquity REST API.

Protocols

Mainnet

The following protocols are currently supported:

• bitcoin
• ethereum
• polkadot
• xrp
• algorand
• stellar

The corresponding constants can be found under platform package.

Testnet

• bitcoin/testnet
• ethereum/ropsten

Pagination

Certain resources contain a lot of data, more than what's practical to return for a single request. With the help of pagination, the data is split across multiple responses. Each response returns a subset of the items requested and a continuation token.

To get the next batch of items, copy the returned continuation token to the continuation query parameter and repeat the request with the new URL. In case no continuation token is returned, there is no more data available.

Table of contents

• Overview
• Installation
• Examples
• Configuration of Server URL
• Authorization
• Transactions signing
• Websocket support
• Utility Methods
• Development
• Documentation

Overview

This API client was generated by the OpenAPI Generator project. By using the OpenAPI-spec from a remote server, you can easily generate an API client.

• API version: 2.0.0
• Package version: 1.0.0
• Build package: org.openapitools.codegen.languages.GoClientCodegen For more information, please visit https://blockdaemon.com

Installation

Pulling dependency

go get gitlab.com/Blockdaemon/ubiquity/ubiquity-go-client

Note: You may need to add this into your ~/.gitconfig in order to make it work with GitLab sub-modules:

[url "ssh://git@gitlab.com/"]
  insteadOf = https://gitlab.com/

Locally

Checkout and install the following dependencies:

go get github.com/stretchr/testify/assert
go get golang.org/x/oauth2
go get golang.org/x/net/context

Put the package under your project folder and add the following in import:

import ubiquity "./ubiquity-go-client/pkg/client"

To use a proxy, set the environment variable HTTP_PROXY:

os.Setenv("HTTP_PROXY", "http://proxy_name:proxy_port")

Examples

See examples in the examples directory:

• tx-querying - querying transaction by id
• current-block - getting current block and printing 10 transactions
• tx-pagination - paginating over transactions
• ws-blocks - subscribing to Websocket channel
• tx-send - sending BTC or ETH transactions and waiting for confirmation throughout Websocket

Configuration of Server URL

Default configuration comes with Servers field that contains server objects as defined in the OpenAPI specification.

Select Server Configuration

For using other server than the one defined on index 0 set context value ubiquity.ContextServerIndex of type int.

ctx := context.WithValue(context.Background(), ubiquity.ContextServerIndex, 1)

Templated Server URL

Templated server URL is formatted using default variables from configuration or from context value ubiquity.ContextServerVariables of type map[string]string.

ctx := context.WithValue(context.Background(), ubiquity.ContextServerVariables, map[string]string{
"basePath": "v2",
})

Note, enum values are always validated and all unused variables are silently ignored.

URLs Configuration per Operation

Each operation can use different server URL defined using OperationServers map in the Configuration. An operation is uniquely identifield by "{classname}Service.{nickname}" string. Similar rules for overriding default operation server index and variables applies by using ubiquity.ContextOperationServerIndices and ubiquity.ContextOperationServerVariables context maps.

ctx := context.WithValue(context.Background(), ubiquity.ContextOperationServerIndices, map[string]int{
	"{classname}Service.{nickname}": 2,
})
ctx = context.WithValue(context.Background(), ubiquity.ContextOperationServerVariables, map[string]map[string]string{
	"{classname}Service.{nickname}": {
		"port": "8443",
	},
})

Authorization

bearerAuth

• Type: HTTP Bearer token authentication

Example

auth := context.WithValue(context.Background(), ubiquity.ContextAccessToken, "BEARERTOKENSTRING")
r, err := client.Service.Operation(auth, args)

Transactions signing

SDK provides a service primitive ubiquitytx.UbiquityTransactionService that you can use to create, sign and send transactions of currently supported protocols - BTC and ETH. See code sample tx-send in examples folder.

Important Note: for BTC, any amount left after sending to destination and change addresses is automatically paid as fee.

Websocket support

SDK comes with a support for Ubiquity Websocket API. Please see the examples ws-blocks and tx-send.

Utility Methods

Due to the fact that model structure members are all pointers, this package contains a number of utility functions to easily obtain pointers to values of basic types. Each of these functions takes a value of the given basic type and returns a pointer to it:

• PtrBool
• PtrInt
• PtrInt32
• PtrInt64
• PtrFloat
• PtrFloat32
• PtrFloat64
• PtrString
• PtrTime

Development

Mocks are generated using https://github.com/vektra/mockery. Run the following command to re-generate tx package mocks:

# Inside pkg/client/tx folder
mockery --dir ../client --name TransactionsAPI --outpkg mocks --output mocks --case snake

Documentation

Additional documentation and examples can be found in the docs directory.