Javascript client library for Skycoin API. This library is a Javascript assembly generated with SWIG to access Skycoin API from Javascript.
- LibJS-skycoin wrappers for the Skycoin cipher
- Make rules
- Development setup
- LibJS Skycoin wrappers for the Skycoin client API
LibJS Skycoin is an assembly that provides wrappers to the Skycoin core cipher API's, implemented in golang
, hence linking directly to the original node code. No transpilation involved.
Before installing, make sure you understand the choices available to install a NPM package . For instance, in case of installing NPM client tools the process would look like this, using npm install
command.
npm install libskycoin
Download the repository from http://github.com/simelo/libjs-skycoin.git.
Execute (make build
) to install the library.
The exported function in Libskycoin JS have the following naming format: SKY_package_func_name
where package is replace by the package where the original Skycoin function is and func_name is the name of the function. For example, LoadConfig
function from cli
package is called in .Net SKY_cli_LoadConfig
All skycoin exported functions return an error object as the last of the return parameters. In .NET error is return as an uint
and it is the first return parameter. The rest of the parameters are returned in the same order.
Receivers in Skycoin are the first of the input parameters. Simple types, like integer, float, string will be used as the corresponding types in JS, except what act as pointers.
Some of Skycoin types are too complex to be exported to a scripting language. So, handles are used instead. Therefore all functions taking a complex type will receive a handle instead of the original Skycoin type. For example, having these functions exported from Skycoin:
func LoadConfig() (Config, error)
func (c Config) FullWalletPath() string
Config is a struct type that is treated as a handle in Libskycoin JS . The usage in .Net will be:
var skycoin = require('./lib/skycoin/build/Release/skycoin');
var configHandle = skycoin.new_Config_HandlePtr();
var err = skycoin.SKY_cli_LoadConfig(configHandle);
if(err == skycoin.SKY_OK) {
// SkY_OK means no error
var fullWalletPath = new _GoString()_;
err = skycoin.SKY_cli_FullWalletPath(configHandle,fullWallerPath);
//Close the handle after using the it
//so the garbage collector can delete the object associated with it.
skycoin.SKY_handle_close( configHandle );
} else {
// #Error
}
}
}
}
Parameters of type byte[] will treated as string . Example, this function in Skycoin:
func (s ScryptChacha20poly1305) Encrypt(data, password []byte) ([]byte, error)
... should be invoked like this:
var encrypt_settings = new skycoin.encrypt__ScryptChacha20poly1305();
var data = new skycoin.GoSlice(); //It will be passed as a parameter of type []byte
var pwd = new skycoin.GoSlice(); //As []byte too
var dataStr = new skycoin._GoString();
var pwdStr = new skycoin._GoString();
var encrypted = new skycoin.GoSlice();
dataStr.setString("Data to encrypt" );
data.convertString(dataStr);
pwdStr.SetString("password");
pwd.convertString(pwdStr);
var err = skycoin.SKY_encrypt_ScryptChacha20poly1305_Encrypt(encrypt_settings, data, pwd,encrypted);
if(err == skycoin.SKY_OK){
encrypted.getString().p); //Encrypted is GoSlice
}
Structures that are not exported as handles are treated like JS classes. In the previous example type ScryptChacha20poly1305 is created in JS like:
var encrypt_settings = new skycoin.encrypt__ScryptChacha20poly1305()
And passed as first parameter in call to SKY_encrypt_ScryptChacha20poly1305_Encrypt
.
Parameters of fixed size array are wrapped in structures when called from JS.
Given these types in Skycoin and this exported function:
type PubKey [33]byte
type SecKey [32]byte
func GenerateDeterministicKeyPair(seed []byte) (PubKey, SecKey)
This is a way to use them to write assertions in JS:
//Generates random seed
var data = new skycoin.GoSlice();
var err = skycoin.SKY_cipher_RandByte(32,data);
var pubkey = new skycoin.cipher_PubKey();
var seckey = new skycoin.cipher_SecKey();
err = skycoin.SKY_cipher_GenerateDeterministicKeyPair(data, pubkey,seckey);
In the example above pubkey
and seckey
are objects of an structure type containing a field named data
holding the corresponding instance of PubKey
and SecKey
. Something like:
cipher_PubKey struct{
data [33]byte;
} cipher_PubKey;
cipher_SecKey struct{
data [32]byte;
} ;
Other slices of base type different from byte
are indeed wrapped inside classes. Let's see how to call the following function:
func GenerateDeterministicKeyPairs(seed []byte, n int) []SecKey
In Javascript this how it should be used to generate a deterministic sequence of pairs of public / private keys given a random seed:
//Generates random seed
var seed = new skycoin.GoSlice();
var err = skycoin.SKY_cipher_RandByte(32,seed);
var seckeys = new skycoin.cipher__SecKeys();
err = skycoin.SKY_cipher_GenerateDeterministicKeyPairs(seed, 2,seckeys);
for(int i=0;i<seckeys.count,i++){
var pubkey = new skycoin.cipher_PubKey();
var seckey = new skycoin.cipher_SecKey();
seckeys.getAt(seckey,i);
skycoin.SKY_cipher_PubKeyFromSecKey(seckey, pubkey);
err = skycoin.SKY_cipher_PubKey_Verify(pubkey);
}
Memory management is transparent to the user. Any object allocated inside the library is left to be managed by the JS garbage collector.
The following make
rules are available after git checkout
of this repository. They all require Skycoin to be checked out as a git submodule
of libskycoin JS .
$ make help
install Build all libraries and tester
test Test all clients
test-node-client Test node client
test-axios-client Test axios client
build-axios-client Build axios client
build-node-client Build node client
build-node-tester Build node client tester
build-axios-tester Build tester
configure Configure build environment
build-libc Build libskycoin C client library
build-swig Generate Node C module from SWIG interfaces
build-libsky-shared Build shared library including SWIG wrappers
It is highly recommended for developers to setup their environment using the available Docker images. Read the LibJS Skycoin Docker docs for further details.
The project has two branches: master
and develop
.
develop
is the default branch and will always have the latest code. The submodule atgopath/src/github.com/skycoin/libskycoin
has to be in sync withskycoin/libskycoin
develop
branch.master
will always be equal to the current stable release on the website, and should correspond with the latest release tag. The submodule atgopath/src/github.com/skycoin/libskycoin
has to be in sync withskycoin/libskycoin
master
branch.
Separate stable development branches will be created to work on releases for supporting the
most recent stable version of Skycoin. The name of these branches should be the Skycoin
major and minor version numbers followed by dev
suffix e.g. 0.25dev
.
These branches may be forked out of either master
or develop
branches, and
the submodule at gopath/src/github.com/skycoin/libskycoin
has to be
in sync with the corresponding tag of skycoin/libskycoin
official repository.
Stable development branches are created most of the time for the following reasons:
- A Skycoin release increasing patch version number.
- Enhanced support and bug fixes for a version of LibJS Skycoin compiled against an stable version of Skycoin
- Backporting useful features added in
develop
.
$ make test
- If the
master
branch has commits that are not indevelop
(e.g. due to a hotfix applied tomaster
), mergemaster
intodevelop
(and fix any build or test failures) - Switch to a new release branch named
release-X.Y.Z
for preparing the release. - Ensure that the submodule at
gopath/src/github.com/skycoin/libskycoin
is in sync with respect to the corresponding tag in https://github.com/skycoin/libskycoin repository. - Run
make build
to make sure that the code base is up to date - Update
CHANGELOG.md
: move the "unreleased" changes to the version and add the date. - Follow the steps in pre-release testing
- Make a PR merging the release branch into
master
- Review the PR and merge it
- Update files in https://github.com/skycoin/repo-info/tree/master/repos/skycoin/remote for
skycoin/skycoindev-js
Docker image, adding a new file for the new version and adjusting any configuration text that may have changed - Tag the
master
branch with the version number. Version tags start withv
, e.g.v0.20.0
. Sign the tag. If you have your GPG key in github, creating a release on the Github website will automatically tag the release. It can be tagged from the command line withgit tag -as v0.20.0 $COMMIT_ID
, but Github will not recognize it as a "release". - Release builds are created and uploaded by travis. To do it manually, checkout the master branch and follow the create release builds instructions.
- Checkout
develop
branch and bump package up to nextdev
version number.
Perform these actions before releasing:
make test
Release builds should be created from master
branch . After updating release version it is necessary to follow these steps
Have installed the node-gyp
for the creation of the package.
https://www.npmjs.com/package/node-gyp
make build
Final results are placed in the lib/skycoin/build/Release/ folder.
LibJS Skycoin contains different clients libraries generated using SWAGGER tools from the latest OpenApi Specification in the GitHub Repository of LibSkycoin.
Name | Swagger Generator |
---|---|
libsky-axios | typescript-axios |
libsky-node | typescript-node |
LibSky-Axios is the client library generated using the typescript-axios Swagger generator.
Before installing, make sure you understand the choices available to install a NPM package . For instance, in case of installing NPM client tools the process would look like this, using npm install
command.
npm install libsky-axios
Download the repository from http://github.com/simelo/libjs-skycoin.git.
Execute (make build
) to build the library. Then
npm install PATH_TO_REPOSITORY/lib/skyapi/axios
Once installed to your project you can use the library as in the example below.
"use strict";
let libsky = require('libsky-axios'); // Import the library
let clientConfig = new libsky.Configuration(); // Create a basic client configuration object
const nodeUrl = 'https://node.skycoin.net'; // Url to a Skycoin Node
let client = new libsky.DefaultApi(clientConfig, nodeUrl); // Create a client object
client.version().then( // Get version data from nodeUrl
result => {
console.log(result.data);
// Print the Version Object in result.data
}
);
LibSky-Node is the client library generated using the typescript-node Swagger generator.
Before installing, make sure you understand the choices available to install a NPM package . For instance, in case of installing NPM client tools the process would look like this, using npm install
command.
npm install libsky-node
Download the repository from http://github.com/simelo/libjs-skycoin.git.
Execute (make build
) to build the library. Then
npm install PATH_TO_REPOSITORY/lib/skyapi/node
Once installed to your project you can use the library as in the example below.
"use strict";
let libsky = require('libsky-node'); // Import the library
const nodeUrl = 'https://node.skycoin.net'; // Url to a Skycoin Node
let client = new libsky.DefaultApi(nodeUrl); // Create a client object
client.version().then( // Get version data from nodeUrl
result => {
console.log(result.data);
// Print the Version Object in result.data
}
);