ForgeSdk v1.1.4 ForgeSdk View Source
Forge is a full fledge blockchain framework for developers to build decentralized applications easily. Forge gives the developers / operators the freedom to launch their own customized chains with their own application logic.
This is the Elixir / Erlang version of the SDK for Forge framework. 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:
- chain APIs: provide the client wrapper for
chain
related gRPC - wallet APIs: provide the client wrapper for
wallet
related gRPC - state APIs: provide the client wrapper for
state
related gRPC - subscription APIs: provide the client wrapper for
subscription
related gRPC - transaction APIs: the gRPC for transaction is
send_tx
, this set of APIs provide helper functions to make building and sending a tx easy. - misc APIs: parsing
configuration
, initialize sdk and more.
Link to this section Summary
Functions
Migrate a wallet
from old address (as well as pk, sk) to a new address
Acquire an asset
from an existing asset factory
One wallet can check in a daily basis to get some free tokens (for test chains only), nonce
should be 0
Create a new asset
Create a new asset factory
This will generate a wallet with default DID type: public key type is ED25519
, hash type is sha3(256)
, and DID role type is account
You can pass in your own DID
type in a map once you want to create a wallet with different settings
Declare a wallet
to the chain
Provide a display friendly result for a data structure
Return the state
for an account, node, validator or application address
Return the state
for an asset
Get a block by its height
. All txs included in this block will be returned
Get a list
of blocks between a range
Retrieve the current status of the chain
Return global state for forge
Retrieve the network info
Retrive the current status of the node
Return an already processed transaction
by its hash
. If this API returns nil
, mostly your tx hasn't been
Retrieve the current validator info
Forge we support multisig
for a tx, you can use this to endorse an already signed tx.
ExchangeTx, ConsumeAssetTx and some other txs are using multisig technology
One wallet can poke in a daily basis to get some free tokens (for test chains only), nonce
should be 0
Subscribe to a topic
. You can event set a filter for the event that you'd listen
Transfer tokens or/and assets
from one wallet to another
Terminate the subscription by the topic id
Update an existing asset
Upgrade the node
to a new version at a given block height
Link to this section Functions
account_migrate(itx, opts) View Source
Migrate a wallet
from old address (as well as pk, sk) to a new address.
Example
old_wallet = ForgeSdk.create_wallet()
declare_tx = ForgeAbi.DeclareTx.new(moniker: "sisyphus")
ForgeSdk.declare(declare_tx, wallet: old_wallet)
new_wallet = ForgeSdk.create_wallet()
wallet_type = new_wallet.address |> AbtDid.get_did_type() |> ForgeSdk.Wallet.Util.to_wallet_type()
itx = ForgeAbi.AccountMigrateTx.new(pk: new_wallet.pk, type: wallet_type, address: new_wallet.address)
ForgeSdk.account_migrate(itx, wallet: old_wallet)
acquire_asset(itx, opts) View Source
Acquire an asset
from an existing asset factory.
Example
w = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "theater"), wallet: w)
w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "tyr"), wallet: w1)
# Note application shall already registered `Ticket` into Forge via `deploy_protocol`.
factory = %{
description: "movie ticket factory",
limit: 5,
price: ForgeAbi.token_to_unit(1),
template: ~s({
"row": "{{ row }}",
"seat": "{{ seat }}",
"time": "11:00am 04/30/2019",
"room": "4"
}),
allowed_spec_args: ["row", "seat"],
asset_name: "Ticket",
attributes: %ForgeAbi.AssetAttributes{
transferrable: true,
ttl: 3600 * 3
}
}
ForgeSdk.create_asset_factory("Avenerages: Endgame", factory, wallet: w)
specs =
Enum.map(["0", "2"], fn seat ->
apply(ForgeAbi.AssetSpec, :new, [%{data: ~s({"row": "15", "seat": "#{seat}"})}])
end)
itx = ForgeAbi.AcquireAssetTx.new(to: address, specs: specs)
ForgeSdk.acquire_asset(itx, wallet: w1)
activate_protocol(itx, opts) View Source
approve_withdraw(itx, opts) View Source
checkin(opts) View Source
One wallet can check in a daily basis to get some free tokens (for test chains only), nonce
should be 0.
Example
w = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: w)
ForgeSdk.checkin(wallet: w)
connect(hostname, opts) View Source
create_asset(itx, opts) View Source
Create a new asset
.
Example
wallet = ForgeSdk.create_wallet()
declare_tx = ForgeAbi.DeclareTx.new(moniker: "sisyphus")
ForgeSdk.declare(declare_tx, wallet: wallet)
ticket = ForgeAbi.Ticket.new(row: "K", seat: "22", room: "3A", time: "03/04/2019 11:00am PST",
name: "Avengers: Endgame")
itx = ForgeAbi.CreateAsset.new(data: ForgeSdk.encode_any!(ticket), readonly: true,
transferrable: true, ttl: 7200)
ForgeSdk.create_asset(itx, wallet: wallet)
create_asset_factory(moniker, factory, opts) View Source
Create a new asset factory
.
Example
w = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "theater"), wallet: w)
w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "tyr"), wallet: w)
# Note application shall already registered `Ticket` into Forge via `deploy_protocol`.
factory = %{
description: "movie ticket factory",
limit: 5,
price: ForgeAbi.token_to_unit(1),
template: ~s({
"row": "{{ row }}",
"seat": "{{ seat }}",
"time": "11:00am 04/30/2019",
"room": "4"
}),
allowed_spec_args: ["row", "seat"],
asset_name: "Ticket",
attributes: %ForgeAbi.AssetAttributes{
transferrable: true,
ttl: 3600 * 3
}
}
ForgeSdk.create_asset_factory("Avenerages: Endgame", factory, wallet: w)
create_wallet()
View Source
create_wallet() :: ForgeAbi.WalletInfo.t()
create_wallet() :: ForgeAbi.WalletInfo.t()
This will generate a wallet with default DID type: public key type is ED25519
, hash type is sha3(256)
, and DID role type is account.
Example
ForgeSdk.create_wallet()
create_wallet(request, conn_name \\ "")
View Source
create_wallet(Keyword.t(), String.t() | atom()) ::
ForgeAbi.WalletInfo.t() | {:error, term()}
create_wallet(Keyword.t(), String.t() | atom()) :: ForgeAbi.WalletInfo.t() | {:error, term()}
You can pass in your own DID
type in a map once you want to create a wallet with different settings.
Example
w1 = ForgeSdk.create_wallet()
ForgeSdk.create_wallet(moniker: "alice")
datetime_to_proto(dt) View Source
deactivate_protocol(itx, opts) View Source
declare(itx, opts) View Source
Declare a wallet
to the chain.
Example
wallet = ForgeSdk.create_wallet()
declare_tx = ForgeAbi.DeclareTx.new(moniker: "sisyphus")
ForgeSdk.declare(declare_tx, wallet: wallet)
declare_node(request, conn_name \\ "") View Source
decode_any(data) View Source
decode_any!(data) View Source
delegate(itx, opts) View Source
deploy_protocol(itx, opts) View Source
deposit_token(itx, opts) View Source
display(data, expand? \\ false) View Source
Provide a display friendly result for a data structure.
Examples
req = ForgeAbi.RequestGetAccountState.new(address: "z1QNTPxDUCbh68q6ci6zUmtnT2Cj8nbLw75")
account_state = ForgeSdk.get_account_state(req)
ForgeSdk.display(account_state)
encode_any(data, type_url \\ nil) View Source
encode_any!(data, type_url \\ nil) View Source
finalize_consume_asset(tx, opts)
View Source
finalize_consume_asset(ForgeAbi.Transaction.t(), Keyword.t()) ::
{:error, any()} | ForgeAbi.Transaction.t()
finalize_consume_asset(ForgeAbi.Transaction.t(), Keyword.t()) :: {:error, any()} | ForgeAbi.Transaction.t()
finalize_create_wallet(tx, opts)
View Source
finalize_create_wallet(ForgeAbi.Transaction.t(), Keyword.t()) ::
{:error, any()} | ForgeAbi.Transaction.t()
finalize_create_wallet(ForgeAbi.Transaction.t(), Keyword.t()) :: {:error, any()} | ForgeAbi.Transaction.t()
finalize_declare(tx, opts)
View Source
finalize_declare(ForgeAbi.Transaction.t(), Keyword.t()) ::
{:error, any()} | ForgeAbi.Transaction.t()
finalize_declare(ForgeAbi.Transaction.t(), Keyword.t()) :: {:error, any()} | ForgeAbi.Transaction.t()
finalize_declare_node(tx, opts) View Source
finalize_exchange(tx, opts)
View Source
finalize_exchange(ForgeAbi.Transaction.t(), Keyword.t()) ::
{:error, term()} | ForgeAbi.Transaction.t()
finalize_exchange(ForgeAbi.Transaction.t(), Keyword.t()) :: {:error, term()} | ForgeAbi.Transaction.t()
finalize_revoke_withdraw(tx, opts) View Source
finalize_withdraw_token(tx, opts) View Source
get_account_state(request, conn_name \\ "")
View Source
get_account_state(
ForgeAbi.RequestGetAccountState.t()
| [ForgeAbi.RequestGetAccountState.t()]
| Keyword.t()
| [Keyword.t()],
String.t() | atom()
) ::
ForgeAbi.AccountState.t()
| nil
| [ForgeAbi.AccountState.t()]
| {:error, term()}
get_account_state( ForgeAbi.RequestGetAccountState.t() | [ForgeAbi.RequestGetAccountState.t()] | Keyword.t() | [Keyword.t()], String.t() | atom() ) :: ForgeAbi.AccountState.t() | nil | [ForgeAbi.AccountState.t()] | {:error, term()}
Return the state
for an account, node, validator or application address.
Example
req = ForgeAbi.RequestGetAccountState.new(address: "z1QNTPxDUCbh68q6ci6zUmtnT2Cj8nbLw75")
ForgeSdk.get_account_state(req)
get_address(hash) View Source
get_asset_state(request, conn_name \\ "")
View Source
get_asset_state(
ForgeAbi.RequestGetAssetState.t()
| [ForgeAbi.RequestGetAssetState.t()]
| Keyword.t()
| [Keyword.t()],
String.t() | atom()
) :: ForgeAbi.AssetState.t() | [ForgeAbi.AssetState.t()] | {:error, term()}
get_asset_state( ForgeAbi.RequestGetAssetState.t() | [ForgeAbi.RequestGetAssetState.t()] | Keyword.t() | [Keyword.t()], String.t() | atom() ) :: ForgeAbi.AssetState.t() | [ForgeAbi.AssetState.t()] | {:error, term()}
Return the state
for an asset.
Example
req = ForgeAbi.RequestGetAssetState.new(address: "zjdjh65vHxvvWfj3xPrDoUDYp1aY6xUCV21b")
ForgeSdk.get_asset_state(req)
get_block(requests, conn_name \\ "")
View Source
get_block(
ForgeAbi.RequestGetBlock.t()
| [ForgeAbi.RequestGetBlock.t()]
| Keyword.t()
| [Keyword.t()],
String.t()
) :: ForgeAbi.BlockInfo.t() | [ForgeAbi.BlockInfo.t()] | {:error, term()}
get_block( ForgeAbi.RequestGetBlock.t() | [ForgeAbi.RequestGetBlock.t()] | Keyword.t() | [Keyword.t()], String.t() ) :: ForgeAbi.BlockInfo.t() | [ForgeAbi.BlockInfo.t()] | {:error, term()}
Get a block by its height
. All txs included in this block will be returned.
Example
req = ForgeAbi.RequestGetBlock.new(height: 1000)
ForgeSdk.get_block(req)
get_blocks(request, conn_name \\ "")
View Source
get_blocks(ForgeAbi.RequestGetBlocks.t() | Keyword.t(), String.t() | atom()) ::
{[ForgeAbi.BlockInfoSimple.t()], ForgeAbi.PageInfo.t()} | {:error, term()}
get_blocks(ForgeAbi.RequestGetBlocks.t() | Keyword.t(), String.t() | atom()) :: {[ForgeAbi.BlockInfoSimple.t()], ForgeAbi.PageInfo.t()} | {:error, term()}
Get a list
of blocks between a range.
Example
page_info = ForgeAbi.PageInfo.new
range_filter = ForgeAbi.RangeFilter.new(from: 1000, to: 1015)
req = ForgeAbi.RequestGetBlocks.new(empty_excluded: true, height_filter: range_filter,
paging: page_info)
ForgeSdk.get_blocks(req)
get_chain_info(conn_name \\ "")
View Source
get_chain_info(String.t()) :: ForgeAbi.ChainInfo.t() | {:error, term()}
get_chain_info(String.t()) :: ForgeAbi.ChainInfo.t() | {:error, term()}
Retrieve the current status of the chain.
Example
ForgeSdk.get_chain_info()
get_config(request, conn_name \\ "") View Source
get_conn(name \\ "") View Source
get_conn_state(name \\ "") View Source
get_delegate_state(request, conn_name \\ "") View Source
get_forge_state(conn_name \\ "")
View Source
get_forge_state(String.t() | atom()) ::
ForgeAbi.ForgeState.t() | {:error, term()}
get_forge_state(String.t() | atom()) :: ForgeAbi.ForgeState.t() | {:error, term()}
Return global state for forge.
Example
ForgeSdk.get_forge_state()
get_forge_stats(requests, conn_name \\ "") View Source
get_health_status(request, conn_name \\ "") View Source
get_net_info(conn_name \\ "")
View Source
get_net_info(String.t()) :: ForgeAbi.NetInfo.t() | {:error, term()}
get_net_info(String.t()) :: ForgeAbi.NetInfo.t() | {:error, term()}
Retrieve the network info
.
Example
ForgeSdk.get_net_info()
get_node_info(conn_name \\ "")
View Source
get_node_info(String.t()) :: ForgeAbi.NodeInfo.t() | {:error, term()}
get_node_info(String.t()) :: ForgeAbi.NodeInfo.t() | {:error, term()}
Retrive the current status of the node.
Example
ForgeSdk.get_node_info()
get_parsed_config(name \\ "") View Source
get_protocol_state(request, conn_name \\ "") View Source
get_stake_state(request, conn_name \\ "") View Source
get_swap_state(request, conn_name \\ "") View Source
get_swap_statistics(request, conn_name \\ "") View Source
get_tx(requests, conn_name \\ "")
View Source
get_tx(
ForgeAbi.RequestGetTx.t()
| [ForgeAbi.RequestGetTx.t()]
| Keyword.t()
| [Keyword.t()],
String.t()
) ::
ForgeAbi.TransactionInfo.t()
| [ForgeAbi.TransactionInfo.t()]
| {:error, term()}
get_tx( ForgeAbi.RequestGetTx.t() | [ForgeAbi.RequestGetTx.t()] | Keyword.t() | [Keyword.t()], String.t() ) :: ForgeAbi.TransactionInfo.t() | [ForgeAbi.TransactionInfo.t()] | {:error, term()}
Return an already processed transaction
by its hash
. If this API returns nil
, mostly your tx hasn't been.
Example
hash = ForgeSdk.send_tx(tx: tx)
ForgeSdk.get_tx(hash: hash)
get_unconfirmed_txs(request, conn_name \\ "") View Source
get_validators_info(conn_name \\ "")
View Source
get_validators_info(String.t()) ::
ForgeAbi.ValidatorsInfo.t() | {:error, term()}
get_validators_info(String.t()) :: ForgeAbi.ValidatorsInfo.t() | {:error, term()}
Retrieve the current validator info.
Example
ForgeSdk.get_validators_info()
list_account(request, conn_name \\ "") View Source
list_asset_transactions(request, conn_name \\ "") View Source
list_assets(request, conn_name \\ "") View Source
list_blocks(request, conn_name \\ "") View Source
list_stakes(request, conn_name \\ "") View Source
list_swap(request, conn_name \\ "") View Source
list_top_accounts(request, conn_name \\ "") View Source
list_transactions(request, conn_name \\ "") View Source
multisig(request, conn_name \\ "")
View Source
multisig(Keyword.t(), String.t() | atom()) ::
ForgeAbi.Transaction.t() | {:error, term()}
multisig(Keyword.t(), String.t() | atom()) :: ForgeAbi.Transaction.t() | {:error, term()}
Forge we support multisig
for a tx, you can use this to endorse an already signed tx.
ExchangeTx, ConsumeAssetTx and some other txs are using multisig technology.
Example
w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: w1)
w2 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "bob"), wallet: w2)
data = Google.Protobuf.Any.new(type_url: "test_asset", value: "hello world")
hash = ForgeSdk.create_asset(ForgeAbi.CreateAssetTx.new(data: asset_data), wallet: w2)
asset_address = ForgeSdk.get_address(hash)
sender_info = ForgeAbi.ExchangeInfo.new(value: ForgeSdk.token_to_unit(1))
receiver_info = ForgeAbi.ExchangeInfo.new(assets: [asset_address])
itx = ForgeAbi.ExchangeTx.new(to: w2.address, sender: sender_info, receiver: receiver_info)
tx = ForgeSdk.prepare_exchange(itx, wallet: w1)
tx1 = ForgeSdk.multisig(tx, w2)
ForgeSdk.send_tx(tx: tx1)
one_token(name \\ "") View Source
poke(itx, opts) View Source
One wallet can poke in a daily basis to get some free tokens (for test chains only), nonce
should be 0.
Example
w = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: w)
hsh = ForgeSdk.checkin(wallet: w)
prepare_consume_asset(itx, opts)
View Source
prepare_consume_asset(map(), Keyword.t()) ::
ForgeAbi.Transaction.t() | {:error, term()}
prepare_consume_asset(map(), Keyword.t()) :: ForgeAbi.Transaction.t() | {:error, term()}
prepare_create_wallet(request, conn_name \\ "")
View Source
prepare_create_wallet(Keyword.t(), String.t() | atom()) ::
{ForgeAbi.WalletInfo.t(), ForgeAbi.Transaction.t()} | {:error, term()}
prepare_create_wallet(Keyword.t(), String.t() | atom()) :: {ForgeAbi.WalletInfo.t(), ForgeAbi.Transaction.t()} | {:error, term()}
prepare_declare(itx, opts)
View Source
prepare_declare(map(), Keyword.t()) ::
ForgeAbi.Transaction.t() | {:error, term()}
prepare_declare(map(), Keyword.t()) :: ForgeAbi.Transaction.t() | {:error, term()}
prepare_declare_node(request, conn_name \\ "") View Source
prepare_exchange(itx, opts)
View Source
prepare_exchange(map(), Keyword.t()) ::
ForgeAbi.Transaction.t() | {:error, term()}
prepare_exchange(map(), Keyword.t()) :: ForgeAbi.Transaction.t() | {:error, term()}
prepare_revoke_withdraw(itx, opts) View Source
prepare_withdraw_token(itx, opts) View Source
refuel(opts) View Source
refuel(itx, opts) View Source
retrieve_swap(itx, opts) View Source
revoke_delegate(itx, opts) View Source
revoke_swap(itx, opts) View Source
search(request, conn_name \\ "") View Source
send_tx(request, conn_name \\ "") View Source
Send tx.
Example
w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: w1)
w2 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "bob"), wallet: w2)
data = Google.Protobuf.Any.new(type_url: "test_asset", value: "hello world")
itx = ForgeSdk.encode_any!(TransferTx.new(to: w2.address, value: new_unit(100)))
tx = ForgeSdk.transfer(itx, wallet: w1, send: :nosend)
hash = ForgeSdk.send_tx(tx: tx)
setup_swap(itx, opts) View Source
stake(itx, opts) View Source
stake_for_node(address, amount, opts) View Source
subscribe(request, conn_name \\ "", opts \\ [])
View Source
subscribe(
ForgeAbi.RequestSubscribe.t() | Keyword.t(),
String.t() | atom(),
Keyword.t()
) :: [ForgeAbi.ResponseSubscribe.t()] | {:error, term()}
subscribe( ForgeAbi.RequestSubscribe.t() | Keyword.t(), String.t() | atom(), Keyword.t() ) :: [ForgeAbi.ResponseSubscribe.t()] | {:error, term()}
Subscribe to a topic
. You can event set a filter for the event that you'd listen.
Example
req = ForgeAbi.RequestSubscribe.new(topic: "fg:t:declare")
ForgeSdk.Rpc.subscribe(req)
token_to_unit(tokens, name \\ "") View Source
transfer(itx, opts) View Source
Transfer tokens or/and assets
from one wallet to another.
Example
w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: w1)
w2 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "bob"), wallet: w2)
data = Google.Protobuf.Any.new(type_url: "test_asset", value: "hello world")
itx = ForgeSdk.encode_any!(TransferTx.new(to: w2.address, value: new_unit(100)))
ForgeSdk.transfer(req, wallet: w1)
unit_to_token(units, name \\ "") View Source
unsubscribe(request, conn_name \\ "", opts \\ [])
View Source
unsubscribe(ForgeAbi.RequestUnsubscribe.t(), String.t() | atom(), Keyword.t()) ::
:ok | {:error, term()}
unsubscribe(ForgeAbi.RequestUnsubscribe.t(), String.t() | atom(), Keyword.t()) :: :ok | {:error, term()}
Terminate the subscription by the topic id
.
Example
req = ForgeAbi.RequestSubscribe.new(topic: "fg:t:declare")
stream_declare = ForgeSdk.Rpc.subscribe(req)
[topic: topic] = Enum.take(stream_declare, 1)
req = ForgeAbi.RequestUnsubscribe.new(topic: topic)
ForgeSdk.Rpc.unsubscribe(req)
update_asset(itx, opts) View Source
Update an existing asset
.
Example
wallet = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice"), wallet: wallet)
post = ForgeAbi.Post.new(title: "a new post", content: "hello world!")
itx = ForgeAbi.CreateAsset.new(itx: ForgeSdk.encode_any!(post))
hash = ForgeSdk.create_asset(itx, wallet: wallet)
address = ForgeSdk.get_address(hash)
new_post = ForgeAbi.Post.new(title: "a new post", content: "Yeah!")
itx = ForgeAbi.UpdateAssetTx.new(data: ForgeSdk.encode_any!(post), address: address)
ForgeSdk.get_asset_state(address: address)
update_consensus_params(itx, opts) View Source
update_validator(itx, opts) View Source
upgrade_node(itx, opts) View Source
Upgrade the node
to a new version at a given block height
.
Example
itx = ForgeAbi.UpgradeNodeTx.new(version: "0.26.0", height: 12000)
ForgeSdk.upgrade_node(itx, wallet: wallet)