Algorand SDK in Python
Project description
py-algorand-sdk
A python library for interacting with the Algorand network.
Installation
Run $ pip3 install py-algorand-sdk
to install the package.
Alternatively, choose a distribution file, and run $ pip3 install [file name]
.
SDK Development
Run tests with make docker-test
Quick start
Here's a simple example you can run without a node.
from algosdk import account, encoding # generate an account private_key, address = account.generate_account() print("Private key:", private_key) print("Address:", address) # check if the address is valid if encoding.is_valid_address(address): print("The address is valid!") else: print("The address is invalid.")
Node setup
Follow the instructions in Algorand's developer resources to install a node on your computer.
Running example.py
Before running example.py, start kmd:
$ ./goal kmd start -d [data directory]
Next, create a wallet and an account:
$ ./goal wallet new [wallet name] -d [data directory]
$ ./goal account new -d [data directory] -w [wallet name]
Visit the Algorand dispenser and enter the account address to fund your account.
Next, in params.py, either update the tokens and addresses, or provide a path to the data directory.
You're now ready to run example.py!
More examples
using the Wallet class
Instead of always having to keep track of handles, IDs, and passwords for wallets, create a Wallet object to manage everything for you.
import params from algosdk import kmd from algosdk.wallet import Wallet # create a kmd client kcl = kmd.KMDClient(params.kmd_token, params.kmd_address) # create a wallet object wallet = Wallet("wallet_name", "wallet_password", kcl) # get wallet information info = wallet.info() print("Wallet name:", info["wallet"]["name"]) # create an account address = wallet.generate_key() print("New account:", address) # delete the account delete = wallet.delete_key(address) print("Account deleted:", delete)
backing up a wallet with mnemonic
import params from algosdk import kmd, mnemonic from algosdk.wallet import Wallet # create a kmd client kcl = kmd.KMDClient(params.kmd_token, params.kmd_address) # create a wallet object wallet = Wallet("wallet_name", "wallet_password", kcl) # get the wallet's master derivation key mdk = wallet.export_master_derivation_key() print("Master Derivation Key:", mdk) # get the backup phrase backup = mnemonic.from_master_derivation_key(mdk) print("Wallet backup phrase:", backup)
You can also back up accounts using mnemonic.from_private_key().
recovering a wallet using a backup phrase
import params from algosdk import kmd, mnemonic # get the master derivation key from the mnemonic backup = "such chapter crane ugly uncover fun kitten duty culture giant skirt reunion pizza pill web monster upon dolphin aunt close marble dune kangaroo ability merit" mdk = mnemonic.to_master_derivation_key(backup) # create a kmd client kcl = kmd.KMDClient(params.kmd_token, params.kmd_address) # recover the wallet by passing mdk when creating a wallet kcl.create_wallet("wallet_name", "wallet_password", master_deriv_key=mdk)
You can also recover accounts using mnemonic.to_private_key().
writing transactions to file
If you don't want to send your transactions now, you can write them to file. This works with both signed and unsigned transactions.
import params from algosdk import algod, kmd from algosdk.future import transaction sender = "sender_address" receiver = "receiver_address" # create an algod and kmd client acl = algod.AlgodClient(params.algod_token, params.algod_address) kcl = kmd.KMDClient(params.kmd_token, params.kmd_address) # get suggested parameters sp = acl.suggested_params() # create a transaction amount = 10000 txn = transaction.PaymentTxn(sender, sp, receiver, amount) # write to file txns = [txn] transaction.write_to_file([txn], "pathtofile.tx")
We can also read transactions after writing them to file.
# read from file read_txns = transaction.retrieve_from_file("pathtofile.tx")
manipulating multisig transactions
import params from algosdk import account, algod, encoding from algosdk.future import transaction acl = algod.AlgodClient(params.algod_token, params.algod_address) # generate three accounts private_key_1, account_1 = account.generate_account() private_key_2, account_2 = account.generate_account() private_key_3, account_3 = account.generate_account() # create a multisig account version = 1 # multisig version threshold = 2 # how many signatures are necessary msig = transaction.Multisig(version, threshold, [account_1, account_2]) # get suggested parameters sp = acl.suggested_params() # create a transaction sender = msig.address() amount = 10000 txn = transaction.PaymentTxn(sender, sp, account_3, amount) # create a SignedTransaction object mtx = transaction.MultisigTransaction(txn, msig) # sign the transaction mtx.sign(private_key_1) mtx.sign(private_key_2) # print encoded transaction print(encoding.msgpack_encode(mtx))
working with NoteField
We can put things in the "note" field of a transaction; here's an example with an auction bid. Note that you can put any bytes you want in the "note" field; you don't have to use the NoteField object.
from algosdk import algod, mnemonic, account from algosdk.future import transaction passphrase = "teach chat health avocado broken avocado trick adapt parade witness damp gift behave harbor maze truth figure below scatter taste slow sustain aspect absorb nuclear" acl = algod.AlgodClient("API-TOKEN", "API-Address") # convert passphrase to secret key sk = mnemonic.to_private_key(passphrase) # get suggested parameters sp = acl.suggested_params() # Set other parameters amount = 100000 note = "Some Text".encode() receiver = "receiver Algorand Address" # create the transaction txn = transaction.PaymentTxn(account.address_from_private_key(sk), sp, receiver, amount, note=note) # sign it stx = txn.sign(sk) # send it txid = acl.send_transaction(stx)
We can also get the NoteField object back from its bytes:
# decode notefield decoded = encoding.msgpack_decode(base64.b64encode(note_field_bytes)) print(decoded.dictify())
working with transaction group
import params from algosdk import algod, kmd from algosdk.future import transaction private_key_sender, sender = account.generate_account() private_key_receiver, receiver = account.generate_account() # create an algod and kmd client acl = algod.AlgodClient(params.algod_token, params.algod_address) kcl = kmd.KMDClient(params.kmd_token, params.kmd_address) # get suggested parameters sp = acl.suggested_params() # create a transaction amount = 10000 txn1 = transaction.PaymentTxn(sender, sp, receiver, amount) txn2 = transaction.PaymentTxn(receiver, sp, sender, amount) # get group id and assign it to transactions gid = transaction.calculate_group_id([txn1, txn2]) txn1.transaction.group = gid txn2.transaction.group = gid # sign transactions stxn1 = txn1.sign(private_key_sender) stxn2 = txn2.sign(private_key_receiver) # send them over network acl.send_transactions([stxn1, stxn2])
working with logic sig
Example below creates a LogicSig transaction signed by a program that never approves the transfer.
import params from algosdk import algod from algosdk.future import transaction program = b"\x01\x20\x01\x00\x22" # int 0 lsig = transaction.LogicSig(program) sender = lsig.address() # create an algod client acl = algod.AlgodClient(params.algod_token, params.algod_address) # get suggested parameters sp = acl.suggested_params() # create a transaction amount = 10000 txn = transaction.PaymentTxn(sender, sp, receiver, amount) # note, transaction is signed by logic only (no delegation) # that means sender address must match to program hash lstx = transaction.LogicSigTransaction(txn, lsig) assert lstx.verify() # send them over network acl.send_transaction(lstx)
working with assets
Assets can be managed by sending three types of transactions: AssetConfigTxn, AssetFreezeTxn, and AssetTransferTxn. Shown below are examples of how to use these transactions.
creating an asset
from algosdk import account from algosdk.future import transaction private_key, address = account.generate_account() # creator _, freeze = account.generate_account() # account that can freeze other accounts for this asset _, manager = account.generate_account() # account able to update asset configuration _, clawback = account.generate_account() # account allowed to take this asset from any other account _, reserve = account.generate_account() # account that holds reserves for this asset fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" total = 100 # how many of this asset there will be assetname = "assetname" unitname = "unitname" url = "website" metadata = bytes("fACPO4nRgO55j1ndAK3W6Sgc4APkcyFh", "ascii") # should be a 32-byte hash default_frozen = False # whether accounts should be frozen by default # create the asset creation transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetConfigTxn(address, sp, total=total, manager=manager, reserve=reserve, freeze=freeze, clawback=clawback, unit_name=unitname, asset_name=assetname, url=url, metadata_hash=metadata, default_frozen=default_frozen) # sign the transaction signed_txn = txn.sign(private_key)
updating asset configuration
This transaction must be sent from the manager's account.
from algosdk import account from algosdk.future import transaction manager_private_key = "manager private key" manager_address = "manager address" _, new_freeze = account.generate_account() # account that can freeze other accounts for this asset _, new_manager = account.generate_account() # account able to update asset configuration _, new_clawback = account.generate_account() # account allowed to take this asset from any other account _, new_reserve = account.generate_account() # account that holds reserves for this asset fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" index = 1234 # identifying index of the asset # create the asset config transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetConfigTxn(manager_address, sp, manager=new_manager, reserve=new_reserve, freeze=new_freeze, clawback=new_clawback, index=index) # sign the transaction signed_txn = txn.sign(manager_private_key)
destroying an asset
This transaction must be sent from the creator's account.
from algosdk import account from algosdk.future import transaction creator_private_key = "creator private key" creator_address = "creator address" fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" index = 1234 # identifying index of the asset # create the asset destroy transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetConfigTxn(creator_address, sp, index=index, strict_empty_address_check=False) # sign the transaction signed_txn = txn.sign(creator_private_key)
freezing or unfreezing an account
This transaction must be sent from the account specified as the freeze manager for the asset.
from algosdk import account from algosdk.future import transaction freeze_private_key = "freeze private key" freeze_address = "freeze address" fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" freeze_target = "address to be frozen or unfrozen" index = 1234 # identifying index of the asset # create the asset freeze transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetFreezeTxn(freeze_address, sp, index=index, target=freeze_target, new_freeze_state=True) # sign the transaction signed_txn = txn.sign(freeze_private_key)
sending assets
from algosdk import account from algosdk.future import transaction sender_private_key = "freeze private key" sender_address = "freeze address" fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" close_assets_to = "account to close assets to" receiver = "account to receive assets" amount = 100 # amount of assets to transfer index = 1234 # identifying index of the asset # create the asset transfer transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetTransferTxn(sender_address, sp, receiver, amount, index, close_assets_to) # sign the transaction signed_txn = txn.sign(sender_private_key)
accepting assets
from algosdk import account from algosdk.future import transaction private_key = "freeze private key" address = "freeze address" fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" receiver = address # to start accepting assets, set receiver to sender amount = 0 # to start accepting assets, set amount to 0 index = 1234 # identifying index of the asset # create the asset accept transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetTransferTxn(address, sp, receiver, amount, index) # sign the transaction signed_txn = txn.sign(private_key)
revoking assets
This transaction must be sent by the asset's clawback manager.
from algosdk import account from algosdk.future import transaction clawback_private_key = "clawback private key" clawback_address = "clawback address" fee_per_byte = 10 first_valid_round = 1000 last_valid_round = 2000 genesis_hash = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" receiver = "receiver address" # where to send the revoked assets target = "revocation target" # address to revoke assets from amount = 100 index = 1234 # identifying index of the asset # create the asset transfer transaction sp = transaction.SuggestedParams(fee_per_byte, first_valid_round, last_valid_round, genesis_hash) txn = transaction.AssetTransferTxn(clawback_address, sp, receiver, amount, index, revocation_target=target) # sign the transaction signed_txn = txn.sign(clawback_private_key)
Documentation
Documentation for the Python SDK is available at py-algorand-sdk.readthedocs.io.
License
py-algorand-sdk is licensed under a MIT license. See the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size py_algorand_sdk-1.3.0-py3-none-any.whl (65.2 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size py-algorand-sdk-1.3.0.tar.gz (62.7 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for py_algorand_sdk-1.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 239d2b1d09864be13aa9dcabf9a68179964c5e903e3b1e06d26d95d17b744b23 |
|
MD5 | 90952b84cc71d0b50879ef9684dfea6b |
|
BLAKE2-256 | 2d5568e25a25defda9b3633018485d2a72514011069ba98ef139f4a8a91ff120 |