Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

A small example package

Project description

Python SDK


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

::: warning This sdk supports python verison >=3.6. :::


Step 0

First get your Forge running on local with Forge CLI.

Step 1

Find the config your forge is using by forge config

Step 2

Set FORGE_CONFIG as your environment variable, pointing to the config your forge is running on.


Level 1: Transfer Money

Scenario: Alice wants to transfer 10 TBA to Mike.

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

Step 1: create wallets for Alice and Mike

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

::: 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.wallet.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.wallet)
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.wallet.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.

>>> transfer_itx = protos.TransferTx(to=mike.wallet.address,value=utils.int_to_biguint(100000000000000000))

>>> rpc.transfer(transfer_itx, alice.wallet)
 hash: "CAEF155B1A3A684DAF57C595F68821502BC0187BEC514E4660BA1BD568474345"

>>> rpc.is_tx_ok('CAEF155B1A3A684DAF57C595F68821502BC0187BEC514E4660BA1BD568474345')

>>> rpc.get_account_balance(mike.wallet.address)

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

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

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

>>> rpc.poke(alice.wallet, alice.token)
hash: "CF0513E473ED13712CDB65EFC196A77BD6193E7DF5124C6233C55732573C85A2"

>>> rpc.get_account_balance(alice.wallet.address)

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.wallet, mike.token)
>>> rpc.is_tx_ok(res.hash)
>>> asset_address

Then we can see how the asset acutally look like.

>>> rpc.get_single_asset_state(asset_address)
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.wallet)
>>> 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.

>>> rpc.get_account_balance(alice.wallet.address)

🎉 🎉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.

Filename, size & hash SHA256 hash help File type Python version Upload date
forge_python_sdk-0.26.11-py2.py3-none-any.whl (116.5 kB) Copy SHA256 hash SHA256 Wheel py2.py3
forge-python-sdk-0.26.11.tar.gz (95.2 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page