General Concepts

There are quite a few new concepts introduced in Forge, before you read one, having a basic idea on these basic concepts would be very helpful to under stand forge.

Introduction

Forge is a framework for users to launch their own decentrailized applications on their own chains.

Forge helps users to build their own chain with three ready-to-use layers: Consensus, Storage, Network Connections. To build a decentralized application, users only need to focus on the top layer: appliciton logic, without worrying infrastructures underneath.

Transactions

The first concept users should understand is a transaction. A transaction is the smallest unit of activites that can happen on ABT Nodes. Everything on an ABT Node are combinations of different transactions. A typical transaction looks like this:

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;
}
1
2
3
4
5
6
7
8
9

Client must fill in necessary values into these fields to get the transaction executed in the chain. Below is an explanation for each field:

  • from: the sender address that initiates the transaction
  • nonce: an integer that track how many transactions this address has sent
  • chain_id: a string that tracks on which chain this transaction happens
  • pk: bytes of public key of sender
  • signature: bytes of sender's signature over this transaction. Used by receiver to verify that the content of this transaction has not been changed by other parties.
  • signatures: extra multisig if this transaction requires extra endorsement from receiver or a 3rd party account. See: What is Multisig?
  • itx: type and content of this transaction. See: transactions

All transactions are backed by transaction protocol. Transaction protocol is the code that executes the transactions and manipulates the states. It can be dynamically installed, upgraded, activated and deactivated on all running nodes of a chain. For more information on transaction protocols, please see [../txs].

Accounts and Wallets

Accounts

To initiate a transaction on an ABT Node, users need to have accounts. Each account has a unique address used by Forge to identify different users. Each user can have an unlimited number of accounts with different addresses.

Wallets

A wallet is a container of accounts's credentials,including the unique address, a Secret Key (SK) and a Public Key(PK). Users use their wallets to send and receive transactions.

message WalletInfo {
  WalletType type = 1;
  bytes sk = 2;
  bytes pk = 3;
  string address = 4;
}
1
2
3
4
5
6
  • type: the cryptographic algorithms used to generate this wallet
  • sk: secrety key
  • pk: public key
  • address: wallet address, which also the account address

Keys

Depending on the type users choose for wallet, public keys are calculated out of secret keys, and addresses are calculated out of public keys. Therefore, secrety keys are very important, because anyone can fake other people's signatures to send malicious transactions with their secrety keys.

Signatures

Each transaction carries a signature generated by sender's SK. By verifying the signature with the sender's PK, which is published on the ABT Node, anyone can verify that the transaction content is the same as the sender has intended.

Inner Transactions(ITX)

Above we have seen the definition of each transaction, where the field itx, which stands for inner transaction decides the type of the transaction and essentially what activity it represents.

For example, TransferTx means this transaction represents a transfer activity where one account is trying to transfer some ammount of money or asset to another account.

Format

Each itx is encoded in google.protobuf.Any format, consisting of type_url and value.

  • type_url: string that represents the identify of this inner transaction, which helps Forge to decide how to decode the value field
  • value: serialized version of the inner transaction.

Type_Urls

Type_urls are strings that help Forge SDK to correctly decode the serialized itx. Each type_url should be registered on forge with the corresponding itx definition. So when Forge sees a type_url, it can grab the correct itx type to decode the value field to get the complete inner transaction.

Since type_urls are used by Forge to interprate the type of itx, it's important that all type_urls follow the same nameing conventions. For example, the type_url of a TransferTx is fg:t:transfer In this case: fg stands for Forge, t for transaction, which means the type of this encoded value is a inner transaction, and transfer stands for the type of this inner transaction.

Every protobuf.Any should contain a type_url that specifies a registered format to decode the encoded value field. Later we will see more use cases of type_urls other than inner transaction.

Values

In protobuf.Any, value contains a serialized version of the inner transaction, which is not human readable.

For example, if we want to transfer 1 unit of currency to some address zysnfkW9LH5jVUubpwcrGaopnN2oDBPTLmuP. The TransferTx looks like:

TransferTx{
    to='zysnfkW9LH5jVUubpwcrGaopnN2oDBPTLmuP',
    value=BigUint(value=b'\x01')
}
1
2
3
4

After serialization, the itx looks like: '\n\x08address1\x12\x03\n\x010' And the entire itx should look like:

Any{
    type_url='fg:t:transfer',
    value='\n\x08address1\x12\x03\n\x010'
}
1
2
3
4

And when ABT Node sees fg:t:transfer, it will know how to decode the value.

Types of Inner Transactions

Above we have seen TransferTx, which represents the transfer activity on an ABT Node. Each activity has its own inner transactions, defined as different types.

For the complete list of itx types and explanations, please see Forge ITX.

gRPC and GraphQL

Forge SDK uses gRPC calls and GraphQL.

Forge SDK has also implemented many ready-to-use GRPC APIs for users to use. Detailed explanation about how Forge SDK uses gRPC can be found here.

Protobuf

To communicate in gRPC, all messages should be in the format of protobuf, which is a format designed to seralize data transferred in gRPC calls.

Last Updated: 5/7/2019, 10:56:40 PM