Forge Elixir SDK

This is the Elixir / Erlang version of the SDK for Forge framework.

What is Forge framework?

Forge is a full fledge blockchain framework for developers to build decentralized applications easily. Unlike other public chain solutions (e.g. Ethereum), forge gives the developers / operators the freedom to launch their own customized chains with their own application logic. For example, one can easily build a chain on top of forge to allow their users to host events and sell event tickets - although centralized services can do this kind of requirements perfectly, giving that data is not owned by centralized service, people can easily exchange tickets freely, without the permission of the original service.

For non-blockchain developers, Forge opened a door to build services that give you the following unique benefits:

What have Forge provided?

In a very high level, a typical blockchain app consists of:

Forge provides these functionalities:

Installation

For every new release we ship osx and ubuntu binaries. If you’re using these two platforms, you can install latest forge-cli:

$ npm install -g @arcblock/forge-cli

And then run:

$ forge init
$ forge start
$ forge web start

Once forge is started, you can open http://localhost:8210 in your browser. Since there’s no any data in your chain (if it is your first run), you can run our simulator to inject some random data:

$ forge simulator start

Forge SDK

To develop applications on top of the forge, you shall pick up a SDK. Forge SDK is intended to make the interaction with the chain built by Forge as easy as possible. All SDK APIs are organized into the following categories:

For more information, please see: Forge SDK overview

Guide for other SDK

Send TX

All common protocol buffers are defined in forge-abi. For example, a general tx structure (defined in https://github.com/ArcBlock/forge-abi/blob/v1.4.0/lib/protobuf/type.proto#L128):

message Transaction {
  string from = 1;
  uint64 nonce = 2;
  string chain_id = 3;
  bytes pk = 4;
  bytes signature = 13;
  repeated Multisig signatures = 14;
  google.protobuf.Any itx = 15;
}

itx means inner transaction. In forge, we supports various itx, including: declare, transfer, exchange, stake, etc. For itx definition, please go to tx.proto. Here’s an example of declare:

message DeclareTx {
  string moniker = 1;
  string issuer = 2;
  google.protobuf.Any data = 15;
}

Once you filled in an itx, you shall wrap it with a google.protobuf.Any. The type_urls defined in forge are:

{:account_migrate, "fg:t:account_migrate", AccountMigrateTx},
{:poke, "fg:t:poke", PokeTx},
{:consume_asset, "fg:t:consume_asset", ConsumeAssetTx},
{:create_asset, "fg:t:create_asset", CreateAssetTx},
{:consensus_upgrade, "fg:t:consensus_upgrade", ConsensusUpgradeTx},
{:declare, "fg:t:declare", DeclareTx},
{:declare_file, "fg:t:declare_file", DeclareFileTx},
{:exchange, "fg:t:exchange", ExchangeTx},
{:stake, "fg:t:stake", StakeTx},
{:sys_upgrade, "fg:t:sys_upgrade", SysUpgradeTx},
{:transfer, "fg:t:transfer", TransferTx},
{:update_asset, "fg:t:update_asset", UpdateAssetTx},

which could be found in here (later on we will extract it into a text file).

For declare itx, the itx is fg:t:declare. Note that the type url in forge use the format simular to urn, with 3 parts:

So once you filled in declare tx, you shall do Google.Protobuf.Any.new(type_url: "fg:t:declare", value: ForgeAbi.DeclareTx.encode(itx)), which ForgeAbi.DeclareTx.encode/1 is the protobuf compiled functionality in your language.

Then you can put the itx into the tx, and provide from, nonce (you can just increment this value for now, later on we will deprecate it), chain_id (e.g. forge). Please leave signature and signatures as protobuf default value. Then you can sign the tx with the following algo:

  1. Do ForgeAbi.Transaction.encode(tx), this will get the bytes of the tx;
  2. Calculate the hash of the encoded tx by using the hash algorithm defined in wallet type;
  3. Sign the hash with the private key;
  4. Do url base64 encode for the signature, and attach it to the tx;
  5. Json encode the tx. And then send it with send_tx graphql API.

Exchange itx

Most of the itx only required single signature, which shall be the sender’s signature, to fulfill the transaction. However, transactions like exchange required multiple signature. To properly sign an exchange tx, we need to follow the simular guide as declare, which, the sender need to attach its signature into the signature field. However, before sending the tx to the chain, the receiver shall attach her signature as well. We have a signatures field, which is a KVPair for this purpose. Receiver first shall verify the signature of the sender is correct (look up the sender state in the chain and verify the signature with its PK from sender’s account state), then sign the entire tx with receiver’s sk (the sign flow is the same, here we use receiver’s wallet type). Then receiver generate a KVPair, with her address as the key, and the signature as the value, and put the pair to the signatures list.

Currently for exchange we just need receiver’s signature. In future, 3rd party may also need to attach its signature into this tx.