Skip to content

Latest commit

 

History

History
251 lines (197 loc) · 10.4 KB

README.md

File metadata and controls

251 lines (197 loc) · 10.4 KB
Raw

Mesh SDK

Go SDK to create and interact with Mesh API implementations

Build once. Integrate your blockchain everywhere.

Overview

The mesh-sdk-go provides a collection of packages used for interaction with the Mesh API specification. Much of the code in this repository is generated from the mesh-specifications repository.

Jump to:

If you have a blockchain based on go-ethereum, we recommend that you use our mesh-geth-sdk SDK.

Getting Started

This Golang project provides a server package that empowers a developer to write a full Mesh Data API server by only implementing an interface. This package automatically validates client requests and calls the functions you implement with pre-parsed requests (instead of in raw JSON).

If you plan to use a language other than Golang, you will need to either codegen a server (using Swagger Codegen or OpenAPI Generator) or write one from scratch. If you choose to write an implementation in another language, we ask that you create a separate repository in an SDK-like format for all the code you generate so that other developers can use it.

Installation Guide

This command installs the Server package.

go get github.com/coinbase/mesh-sdk-go/server

Components

Router

The router is a Mux router that routes traffic to the correct controller.

Controller

Controllers are automatically generated code that specify an interface that a service must implement.

Services

Services are implemented by you to populate responses. These services are invoked by controllers.

Recommended Folder Structure

main.go
/services
  block_service.go
  network_service.go
  ...

Quick Examples

Complete SDK Example

This is an example of how to write an implementation using the Server package in mesh-sdk-go.

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/coinbase/mesh-sdk-go/asserter"
	"github.com/coinbase/mesh-sdk-go/examples/server/services"
	"github.com/coinbase/mesh-sdk-go/server"
	"github.com/coinbase/mesh-sdk-go/types"
)

const (
	serverPort = 8080
)

// NewBlockchainRouter creates a Mux http.Handler from a collection
// of server controllers.
func NewBlockchainRouter(
	network *types.NetworkIdentifier,
	asserter *asserter.Asserter,
) http.Handler {
	networkAPIService := services.NewNetworkAPIService(network)
	networkAPIController := server.NewNetworkAPIController(
		networkAPIService,
		asserter,
	)

	blockAPIService := services.NewBlockAPIService(network)
	blockAPIController := server.NewBlockAPIController(
		blockAPIService,
		asserter,
	)

	return server.NewRouter(networkAPIController, blockAPIController)
}

func main() {
	network := &types.NetworkIdentifier{
		Blockchain: "Mesh",
		Network:    "Testnet",
	}

	// The asserter automatically rejects incorrectly formatted
	// requests.
	asserter, err := asserter.NewServer(
		[]string{"Transfer", "Reward"},
		false,
		[]*types.NetworkIdentifier{network},
		nil,
		false,
		"",
	)
	if err != nil {
		log.Fatal(err)
	}

	// Create the main router handler then apply the logger and Cors
	// middlewares in sequence.
	router := NewBlockchainRouter(network, asserter)
	loggedRouter := server.LoggerMiddleware(router)
	corsRouter := server.CorsMiddleware(loggedRouter)
	log.Printf("Listening on port %d\n", serverPort)
	log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", serverPort), corsRouter))
}

SDK Packages

  • Types: Auto-generated Mesh types
  • Client: Low-level communication with any Mesh server
  • Server: Simplified Mesh API server development
  • Asserter: Validation of Mesh types
  • Fetcher: Simplified and validated communication with any Mesh server
  • Parser: Tool for parsing Mesh blocks
  • Syncer: Sync Mesh blocks with customizable handling
  • Reconciler: Compare derived balances with node balances
  • Keys: Cryptographic operations for Mesh-supported curves
  • Constructor: Coordinate the construction and broadcast of transactions

These packages are demoed extensively in examples and are utilized throughout the mesh-cli tool.

Syncer

The core of any integration is syncing blocks reliably. The syncer serially processes blocks from a Data API implementation (automatically handling re-orgs) with user-defined handling logic and pluggable storage. After a block is processed, store it to a DB or send a push notification—the decision is up to you!

Parser

When reading the operations in a block, it's helpful to apply higher-level groupings to related operations, or match operations in a transaction to some set of generic descriptions (i.e., ensure there are two operations of equal but opposite amounts). The parser empowers any integrator to build abstractions on top of the building blocks that the Mesh API exposes.

Development

Helpful commands for development:

Install Dependencies

make deps

Generate Types, Client and Server

make gen

If you want to modify client and server, please modify files under templates/client and templates/server then run make gen

Run Tests

make test

Lint the Source Code

This includes the generated code.

make lint

Code Check

make release

Testing

To validate mesh-sdk-go, install mesh-cli and run one of the following commands:

  • mesh-cli check:data --configuration-file mesh-cli-conf/testnet/config.json - This command validates that the Data API implementation is correct, using the bitcoin testnet node. It also ensures that the implementation does not miss any balance-changing operations.
  • mesh-cli check:construction --configuration-file mesh-cli-conf/testnet/config.json - This command validates the Construction API implementation. It also verifies transaction construction, signing, and submissions to the testnet network.
  • mesh-cli check:data --configuration-file mesh-cli-conf/mainnet/config.json - This command validates that the Data API implementation is correct, using the bitcoin mainnet node. It also ensures that the implementation does not miss any balance-changing operations.

Read the How to Test your Mesh Implementation documentation for additional details.

Contributing

You may contribute to the mesh-sdk-go project in various ways:

Read our Contributing documentation for more information.

Documentation

You can find the Mesh API documentation here.

Check out the Getting Started section to start diving into Mesh.

Related Projects

  • mesh-specifications — The mesh-specifications repository generates the SDK code in the mesh-sdk-go repository.
  • mesh-cli — Use the mesh-cli tool to test your Mesh API implementation. The tool also provides the ability to look up block contents and account balances.
  • mesh-geth-sdk – The mesh-geth-sdk repository provides a collection of packages used for interaction with the Mesh API specification. The goal of this SDK is to help accelerate Mesh API implementation on go-ethereum based chains.

Sample Implementations

To help you with examples, we developed complete Mesh API sample implementations for Bitcoin and Ethereum. Developers of Bitcoin-like or Ethereum-like blockchains may find it easier to fork these implementation samples than to write an implementation from scratch.

You can also find community implementations for a variety of blockchains in the mesh-ecosystem repository.

License

This project is available open source under the terms of the Apache 2.0 License.

© 2022 Coinbase