mysql-seascape-extension

README

SeascapeSDS Guide

this is the golang package of the SeascapeSDS

Seascape Software Development Service is the right toolbox to build feature rich applications on a blockchain.

---

Whenever you write a dapp, you also write the additional tools around the smartcontracts.

• You write an unnecessary software that frequently reads the blockchain to update your backend.
• You write an unnecessary tool that signs the transaction to change the state of smartcontract.
• You need to write calculations for metadata. Such as representing token in fiat currency, or calculating APY/APR for defi project as we faced in during mini-game development.

These tools are not exactly blockchain related. Most of the smartcontract developers doesn't required to write them. Its the burden of the backend developers.

You would be amazed how many backend developers fail during the development of these basic tools. Surprisingly it requires a good knowledge of the blockchain's API and internal work. Yet, the learning curve is quite long and painful.

Knowing these facts, there are popping a lot of startups that provides these tools for a fee. How many messages I am getting every day on my professional email, or personal email from outsourcing companies that tries to get overpriced money for such tools.

Let me give you more examples!

What if your application is cross-chain, let's say your NFT or Token is cross-chain.

Or you want to utilize additional features in your smartcontracts, maybe oracles or schedulers. In that case each of them has their own cryptocurrency. You have to manage multi-currency for your single dapp.

You still wonder, why there is no big "play2earn" games and dapps?

It comes from the expertise of the game developers working in the crypto space since 2018.

---

Enter SeascapeSDS

Consider SeascapeSDS as the list of three linked tools.

• cli – for smartcontract developer
• sds – for processing smartcontract
• sdk – for backend developer

The smartcontract developer deploys the smartcontract with cli, and all the tools to read data, to write the data appear on sds. Then the backend developer who wants to read the data or send the data uses sdk.

Since SeascapeSDS (all three are open-source), if you don't have the feature that you want, then you can create it on your own or ask the community to build it for you.

The blockchain is a complex an advanced technology. To create the big innovations, working as a single team is not enough. We should work together and share the experiences (which is SeascapeSDS) to push the innovations.

Right, let the cryptocurrency of each project "go to the moon" because of its popularity and its users, not because of the underlying technology.

---

Installation

Prerequirements

Building the package

Go

The SDS core is written in Go programming language, therefore we need Go to be installed on the machine. Visit the go official website for installation instructions.

Once you have go installed, you can import SDS into your go project as:

go get github.com/blocklords/sds

###ZeroMQ

Internally, SDS relies on ZeroMQ C (programming language) library. SDS uses pebbe/zmq4 – a go wrapper around C library.

💡 Detailed instructions pebbe/zmq4/requirements

Enable CGO:

In Centos8:

export CGO_ENABLED=1

Go with CGO enabling depends on GCC.

In Centos8:

yum install dnf && dnf group install "Development Tools"

The successfull installation should have gcc to be available on the Terminal.

Install Zeromq and its dependencies

In Centos8

yum install epel-release && yum install zeromq-devel

The official Centos repository doesn't include Zeromq, therefore, we first install epel repository.

---

Example

Create a new folder for the project:

mkdir hello-sds
cd hello-sds
go init github.com/example/hello-sds

Then install the SDS package:

go get github.com/blocklords/sds

Let's assume that the smartcontract developer deployed the smartcontract on a blockchain. He did it using SDS CLI. Now our smartcontract is registered on SeascapeSDS.

For example let's work with ScapeNFT. Its registered on the SeascapeSDS as:

{
	organization: "seascape"
  project:      "core"
  network_ids:  ["1", "56", "1284"]
  group:        "nft"
  name:         "ScapeNFT"
}

With the gosds package installed, let's create the .env file with the authentication parameters.

Installation process of gosds and its setup requirements will be added later.

Here is the sample code that tracks all NFT events from Seascape organization in all networks.

package main

import (
	"fmt"
	"log"

	"github.com/Seascape-Foundation/sds-service-libconfiguration/env"
	"github.com/Seascape-Foundation/sds-service-libcommunication/message"
	"github.com/Seascape-Foundation/sds-common-libtopic"
	"github.com/blocklords/sds/sdk"
)

func main() {
	filter := topic.TopicFilter{
		Organizations: []string{"seascape"},
		Groups:        []string{"nft"},
	}

	subscriber, _ := sdk.NewSubscriber(&filter, true)
	subscriber.Start()

	for {
		reply := <-subscriber.Channel

		if reply.Status == message.FAIL {
			fmt.Fatalf("received an error %s", reply.Message)
			break
		}


		for _, event := range reply.Parameters.Logs {
			event_name := event.Name
			event_parameters := event.Parameters

			fmt.Printf("Event Name: '%s'\n", event_name)
			fmt.Printf("Parameters: %v\n", event_parameters)
			fmt.Printf("Network: %s\n", event.SmartcontractKey.NetworkId)
			fmt.Printf("Timestamp %d\n", event.BlockHeader.Timestamp)

			// Do something with the event logs
		}
	}
}

That's all! No need to know what is the smartcontract address, to keep the ABI interface (If you know what are these terms mean).

SeascapeSDS will care about the network issues, about smartcontract ABI and its address.

Now let's discuss about about the code.

Very important thing there is the topic filter variable. In the topic, we listed the smartcontract name: ScapeNFT, but we didn't list the network ids (remember that the NFT is deployed on Ethereum, BNB Chain and Moonriver).

By omitting network ids, Scape NFT on any network will be received by the backend.

If you want for example to track ScapeNFTs on BNB Chain then change the topic filter to:

filter := topic.TopicFilter{
    Organizations:  []string{"seascape"},
    Projects:       []string{"core"},
    Smartcontracts: []string{"ScapeNFT"},
    NetworkIds:     []string{"1"},
    Methods:        []string{"transfer"},
}

• If you want to track any transaction, then remove the Methods.
• If you want to track any nft in the seascape ecosystem, then 1. delete the Smartcontracts, Projects, add the Groups: []string{"nft"}.

Once we got the transactions, what about the parameters of the transactions? In the example above we listed three arguments as:

nft_id := tx.Args["_nftId"]
from := tx.Args["_from"]
to := tx.Args["_to"]

The names of the arguments are identical how they are written in the source code.

On the roadmap, we have a plan want to generate a documentation by AI. AI will parse the smartcontract interface, and will set the basic use cases with copy-paste code. Write, the less developer writes, the better it is.

💡 More examples Coming soon.

---

Source code

If you want to run SDS in your local computer, then we need two external applications: Database and Vault.

💡 Tip You can skip the Vault if you run the application with --plain argument.

There are two options how to install them: Install manually or by docker.

Docker

The docker package also comes with the UI for vault and Database.

Docker and Docker Compose

For local production you would need docker and docker-compose. Installation of Docker Desktop will install docker-compose file as well.

---

Install images

📝 For Linux Before you install images, you should create _db/mysql and _db/mysql_logs directories.

To install database image only:

docker compose up -d sds-db

or if you want to install both database and vault along with the UI.

docker compose up -d

• database web UI: http://localhost:8088/ username: root password: tiger
• vault web UI: http://localhost:8200/ui/ Login into vault web UI will require key part and root token. Both are stored in ./_vault/tokens/root.json. The key part="keys_base64". The root token="root_token"

Manually

Follow the Mysql database and Hashicorp Vault websites to install on your machine.

Setup Database

Once we have Database, we need to setup for SDS. This example assumes that you've using Database via Docker.

Create a new database.

In terminal:

docker exec -it sds-db bash
mysql -u root -p

For password type tiger. In the Mysql create the SDS database:

CREATE DATABASE sds_dev `
CHARACTER SET utf8 COLLATE utf8_general_ci;

Then exit from mysql and from container by typing exit twice.

On UI:

1 Go to http://localhost:8080/ 2 Login with username root and password tiger. 3 On the panel, click the New button to create the database. 4 Name of the database. For example: sds_dev 5 Encoding format should be utf8_general_ci.

Install migration tool

We use goose. Follow the Installation page to setup on your machine.

In our example we store the goose binary in /_db/bin/ directory.*

Migrate tables

In the sds root directory, run the following:

./_db/bin/goose `
-dir ./_db/migrations `
mysql "root:tiger@/sds_dev" `
up

The root is the username, tiger is the password. sds_dev is the database name that we created during Create a new database step.

📝 Creating a new migration

./_db/bin/goose `
-dir ./_db/migrations `
mysql "root:tiger@/sds_dev" `
create <action_name> sql

Minimum environment

Create .env in the root from where you call the binary.

SDS_DATABASE_NAME=sds_dev

Build binary

go build -o ./bin/sds

On Windows

go build -o ./bin/sds.exe

Run SDS

./bin/sds --plain ./.env

Next

Either set the Security or Install SDS Gateway. Or setup the configurations.

---

Security

SeascapeSDS Core

This go module contains the core features and SDK along together.

This repository isn't enough to run the SeascapeSDS in your machine.

The following set ups are necessary for running on your machine:

• Vault for keeping credentials
• Mysql Database
• sds-ts keeps the other core services that are written in Typescript.
• .env with the SeascapeSDS Service ports, its configuration, vault access and database parameters.

SDS Configuration

We can set the following environment variables

Name	Default	Description
SDS_BLOCKCHAIN_NETWORKS		See Network section
CORE_PORT	4001	The SDS is available for SDS Gateway on this port
SDS_DATABASE_NAME	seascape_sds	The database name
SDS_DATABASE_PORT	3306	The database port
SDS_DATABASE_HOST	localhost	The database host
SDS_DATABASE_TIMEOUT	10	The request timeout seconds. If database doesn't responde within the timeout, then SDS will terminate or return an error
SDS_REQUEST_TIMEOUT	30	The request timeout in Seconds. Any request from one thread or process to another (whether its internal or remote) handles SDS_REQUEST_TIMEOUT seconds. If the remote service doesn't respond within the timeout, then SDS will reconnect. It goes along with with SDS_REQUEST_ATTEMPT
SDS_REQUEST_ATTEMPT	5	Amount of reconnects that SDS is trying to do. If the remote thread or process doesn't respond within SDS_REQUEST_TIMEOUT seconds, then SDS will make SDS_REQUEST_ATTEMPT attempts. If the remote thread or process doesn't responde with all attempts, then SDS will return an error.
SDS_IMX_REQUEST_PER_SECOND	20	How many requests SDS can do to the remote Imx provider. This parameter sets the limit that is managed by SDS. The more smartcontracts are registered on imx network, the slower the fetch speed.

Network

SDS_BLOCKCHAIN_NETWORKS=[{"id":"56","providers":[{"url":"https://rpc.ankr.com/bsc","length": 32}],"type":"evm"}]

Add any EVM based networks or ImmutableX based networks in the environment variable. The value is the JSON array with Network objects in the single line.

Here is the format of the JSON value:

[
	{
		"id":"56",
		"providers":[
			{
				"url":"https://rpc.ankr.com/bsc",
				"length": 32
			},
			{
				"url": "https://binance.nodereal.io",
				"length": 32
			}
		],
		"type": "evm"
	}
]

Description of the parameters

• "id" – string Network ID. For EVM based networks its identical to the Chain ID.
• "type" – string Type of Blockchain. Supported types are: evm and imx.
• "providers" – Array of Providers.

You can set multiple providers for each network. SDS is smart enough to use all of the providers for the blockchain requests.

Description of the Provider parameters:

• "url" – string HTTP path to the remote blockchain node RPC.
• "length" – Number Amount of blocks that SDS could fetch from the remote RPC.

Once you set the SDS, stop binary, and re-run to enable the new networks.

Testing

⚠ Docker It requires docker and docker host exposing.

For Windows we need to expose the deamon

• Settings
• General
• Checkmark the Expose Deamon
• Restart the docker engine

Then you need to set the DOCKER_HOST. On powershell

 $env:DOCKER_HOST="tcp://localhost:2375"

Run recursively

go test ./...

Documentation

Overview

The database package handles all the database operations. Note that for now it uses Mysql as a hardcoded data

The database is creating a new service with the inproc reply controller. For any database operation interact with the service.