Skip to main content

A small example package

Project description



For details about how to set up Forge, please checkout Forge.

A more detailed reference manual for forge-python-sdk can be found Here.


We recommend installing through pip

pip install forge-python-sdk

For developers:

pip install -r requirements.txt


Step 0

First get your Forge running on local with Forge CLI.

Step 1

Create a Forge Connection with your Forge port (Default is if your Forge runs with forge-cli)

from forge_sdk import ForgeConn
f = ForgeConn('')
rpc = f.rpc
config = f.config

::: warning This step applies to every tutorial :::


Level 1: Transfer Money

Scenario: Alice wants to transfer 10 TBA to Mike.

::: tip Notes TBA is the default currency on Forge Chain. If 1 TBA has 16 digits, it shows as 10000000000000000. :::

Step 1: create wallets for Alice and Mike

from forge_sdk import protos, utils
alice = rpc.create_wallet(moniker='alice')
mike = rpc.create_wallet(moniker='mike')

::: tip Notes moniker is a nickname for this wallet on Forge. passphrase is used by Forge to encrypt the wallet into a keystore file. More details about wallet declaration rules are here. :::

Let's take a look at Alice's wallet and here account details

>>> alice
token: "886fe22cd8d29a5c0d0fa5b21ec448bd"
wallet {
  sk: "\274\262\331z\000\265\374\271O7f\2640<\214\212G\302y\021\232\363\355.E\207\213&\355\362\260Gu\204\360@e\036\353\357\276\323\340\211\371U\3716\2212\304\223\037{\037\366\267\374\233@\021\215W\027"
  pk: "u\204\360@e\036\353\357\276\323\340\211\371U\3716\2212\304\223\037{\037\366\267\374\233@\021\215W\027"
  address: "z1brhJCteRSvHUQ9BytsZePkY4KJ9LFBayC"

>>> rpc.get_account_balance(alice.address)

Step 2: Help Alice send a Poke Transaction to get some money

Now you have created wallets for Alice and Mike, but there's no money in their accounts. Let's help Alice to earn some money by sending a Poke transaction.

>>> rpc.poke(alice)
hash: "CF0513E473ED13712CDB65EFC196A77BD6193E7DF5124C6233C55732573C85A2"

Receiving the hash means the transaction has been passed to Forge, but doens't mean the transaction is successful. To confirm that the transaction is sent successfully, let's dive deeper into the tranaction details.

>>> rpc.is_tx_ok('CF0513E473ED13712CDB65EFC196A77BD6193E7DF5124C6233C55732573C85A2')

If is_tx_ok returns True, that means the transaction has been executed successfully. Now Alice should have 25 TBA in her account.

Now let's check Alice's account balance. There should be 25 TBA.

>>> rpc.get_account_balance(alice.address)

::: tip Notes Poke: Each account can send a Poke Transaction to get 25 TBA each day. Hash: The calculated hash of the signed transaction. Each transaction should have its own unique hash. :::

Step 3: Transfer the money from Alice to Mike

Now Alice has 25 TBA in her account and Mike has nothing. We can help Alice transfer 10 TBA to Mike by sending out a transfer transaction.

 hash: "CAEF155B1A3A684DAF57C595F68821502BC0187BEC514E4660BA1BD568474345"



Now we can see tht Alice just successfully transferred 10 TBA to Mike's Account!

🎉 Congratulations! You have finished the Level 1 tutorial! Now you should have a general sense about how Forge works. If you want more challenges, go checkout the Level 2 tutorial.

Level 2: Sell a Used Laptop

Scenario: Mike wants to sell a used laptop to Alice.

Step 1: Create accounts for Alice and Mike

mike = rpc.create_wallet(moniker='mike')

After creating accounts for Alice and Mike, we help Alice to get some money to buy Mike's laptop

hash: "CF0513E473ED13712CDB65EFC196A77BD6193E7DF5124C6233C55732573C85A2"


Step 2: Create a laptop asset for Mike

In real world, Mike could have just sold Alice his laptop. With Forge SDK, any physical item can exist in the form of asset.

Let's try to help Mike create a laptop asset with the CreateAssetTx. The data field is for users to put item-specific information, where type_url is hints for how to decode the serialized value field. In this tutorial, for simplicity purpose, we only put the name of thel laptop.

res, asset_address= rpc.create_asset('test:name:laptop', b'Laptop from Mike',mike, mike.token)

Then we can see how the asset acutally look like.

address: "zjdwghZpZN45ig6ytP74r8VF9CHhQtEjBype"
owner: "z1QyzoxdPPEk9A2Uz6h18rvjsAHtmJ78mGD"
transferrable: true
issuer: "z1QyzoxdPPEk9A2Uz6h18rvjsAHtmJ78mGD"
stake {
  total_stakes {
    value: "\000"
  total_unstakes {
    value: "\000"
  total_received_stakes {
    value: "\000"
  recent_stakes {
    type_url: "fg:x:address"
    max_items: 128
    circular: true
  recent_received_stakes {
    type_url: "fg:x:address"
    max_items: 128
    circular: true
context {
  genesis_tx: "9EAC9AF9136D30E5C02EDD46BEF081AD61F3F722BA6FEF4398CC5FBC363DCA30"
  renaissance_tx: "9EAC9AF9136D30E5C02EDD46BEF081AD61F3F722BA6FEF4398CC5FBC363DCA30"
  genesis_time {
    seconds: 1557129670
    nanos: 700917000
  renaissance_time {
    seconds: 1557129670
    nanos: 700917000
data {
  type_url: "test:name:laptop"
  value: "Laptop from Mike"

The laset field is the data field, where we can see Laptop from Mike. You can also put more complicated information inside, like serialized protobuf message.

Step 3 : Exchange the asset with money

Now Alice has 25 TBA in her account, and Mike has a laptop asset. What should Mike do if he wants to sell the laptop asset for 10 TBA? He can initiate an ExchangeTx.

Since Mike is going to be the sender, we put the laptop asset_address as what he will exchange. Similarly, Alice will exchange 10 TBA.

mike_exchange_info = protos.ExchangeInfo(assets=[asset_address])
alice_exchange_info = protos.ExchangeInfo(value = utils.int_to_biguint(100000000000000000))
exchange_tx = protos.ExchangeTx(sender = mike_exchange_info, receiver=alice_exchange_info)

tx = rpc.prepare_exchange(exchange_tx, mike)
tx = rpc.finalize_exchange(tx, alice.wallet)
res = rpc.send_tx(tx)

>>> rpc.is_tx_ok(res.hash)

In the prepare_exchange, we ask Mike the seller to verify the transaction; and in the finalize_exchange, we ask Alice the buyer to verify the transaction. After both parties have verified, we can send the transaction directly.

Now if we check the laptop's owner, it should be Alice's address.

rpc.get_single_asset_state(asset_address).owner == alice.wallet.address

Alice's account should have only 15 TBA after she pays for the laptop.


🎉 🎉Congratulations! You have finished the Level 2 tutorial! Now you should have a general sense about how to create an asset and exchange assets with Forge SDK. Try and create more complicated assets!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

forge-python-sdk-0.39.0.tar.gz (102.0 kB view hashes)

Uploaded source

Built Distribution

forge_python_sdk-0.39.0-py2.py3-none-any.whl (135.4 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page