API

Models

Account

djwebdapp.models.account_setup(sender, instance, **kwargs)

Initial account setup, pre_save signal.

If the Account is created with a secret_key and without any address and the Blockchain.provider supports it, then it will fetch the address automatically.

If the Account is created without an address nor a secret_key then it is considered that you are creating a new wallet and the djwebdapp.provider.Provider.generate_secret_key() method will generate a py:attr:~Account.secret_key.

If the balance is not set at all, then it will be set with the refresh_balance() method.

class djwebdapp.models.Account(*args, **kwargs)

A blockchain account.

name

Optionnal name for this account.

description

Optionnal description for this account.

created_at

Automatic datetime of the creation of this account in the database.

updated_at

Automatic datetime of the last update of this account in the database.

address

Account address on the blockchain.

blockchain

Foreign key to the Blockchain model this account is related to.

balance

Decimal balance of this account, updated by the refresh_balance() method. with the refresh_balances management command. Uses

owner

Foreign key to your User model which owns this account, if any.

secret_key

djfernet encrypted private key of this account.

This is used to sign transactions. The secret key must be set with the set_secret_key() method.

A secret key is generated automatically by the account_setup() function if the account is not created with a address.

counter

Counter of transactions sent from this account.

last_level

Last block level when a transaction was sent from this account.

index

Boolean to indicate wether the indexer should index all transactions or not.

exception DoesNotExist

exception MultipleObjectsReturned

get_secret_key()

Returns the account binary secret key.

property provider

Return a Provider instance for this wallet.

The provider_cls returns the class that will be used.

refresh_balance(commit=True)

Refresh the balance of this account.

Using get_balance(), it will update balance field and save the model.

Then, return the balance.

Parameters:

commit – Needs to be True for this method to actually save the model.

set_secret_key(value)

Set the encrypted secret key.

Parameters:

value – The secret key to set.

Blockchain

class djwebdapp.models.Blockchain(*args, **kwargs)

Class to represent a blockchain.

name

Name of the blockchain.

provider_class

Provider class to use for this blockchain.

is_active

Boolean to indicate wether this blockchain is active or not.

description

Optionnal description for this blockchain.

unit

Unit name of the blockchain, ie. eth, xtz…

unit_micro

Unit name of the smallest unit of the blockchain, ie. wei, mutez…

index_level

Highest indexed level.

min_level

Lowest indexed level

min_confirmations

Number of confirmation blocks from confirm to done states.

exception DoesNotExist

exception MultipleObjectsReturned

property provider

Return a fresh instance of the provider class bound to self.

property provider_cls

Return the imported provider class.

wait()

Wait for all transactions to be confirmed by min_confirmations blocks.

For use in between spool and index calls:

blockchain.provider.spool()
blockchain.wait()
blockchain.provider.index()

wait_blocks(blocks=None)

Wait for the blockchain head to advance a number of blocks.

wait_level(level)

Wait for the blockchain head to reach a given level.

Node

class djwebdapp.models.Node(*args, **kwargs)

Blockchain node that we can use to query.

blockchain

Foreign key to the Blockchain model this node is related to.

name

Node name, generated from endpoint if empty.

endpoint

Node endpoint to query.

is_active

Boolean to indicate wether this node is active or not.

priority

Nodes with the highest priority will be used first.

exception DoesNotExist

exception MultipleObjectsReturned

Transaction

djwebdapp.models.dependency_graph(sender, instance, **kwargs)

If the transaction is a contract call, then add the contract as dependency.

class djwebdapp.models.Transaction(*args, **kwargs)

Transaction superclass, base for all blockchain-specific classes.

normalizer_class

Name of the Normalizer subclass to call to normalize blockchain transactions for contracts subclassing this model.

id

UUID primary key.

created_at

Datetime when the transaction was created.

updated_at

Datetime when the transaction was last updated.

name

Optional free label name.

description

Optional description text.

blockchain

Foreign key to the Blockchain model this transaction is related to.

level

Level of the blockchain when the transaction was send.

hash

Transaction hash.

counter

Transaction counter. Used to avoid replay attack. This counter is filled by the blockchain provider.

nonce

Transaction nonce. Used to order transactions in the same block.

gasprice

Gas price used to send the transaction.

gas

Number of gas used to send the transaction.

last_fail

If the transaction failed, this field contains the datetime of the last failure.

max_fails

Number of failures to retry before aborting transaction.

has_code

If the transaction is a contract creation, and the transaction contains the deployed contract code, this field is set to True.

metadata

This field contains the metadata of the transaction.

normalized

Enabled when transaction is normalized. Set True by the normalize() method.

state

Status of the transaction. By default, the transaction is in the deploy state. When the transaction is indexed, the state is set to done. The state is updated by the state_set() method.

error

If the transaction failed, this field contains the error message.

history

History of the state of the transaction associated with the datetime of the state change.

amount

Amount send by the transaction if there is.

args

Arguments, appliable to deployments or method calls.

address

Contract address, appliable to method calls.

function

Function name, if this is a method call.

sender

Sender Account that send the transaction.

receiver

Receiver Account , if this is a transfer.

kind

Kind of transaction. Can be contract, function or transfer.

index

Boolean to indicate wether the indexer should index all transactions or not.

contract

Smart contract related to this transaction, appliable to method call transactions.

caller

Transaction that called this one, if any.

target_contract

In your own subclasses for function calls, this should be an FK to the contract subclass, then save() will provision contract from the parent model of the target contract.

entrypoint

In your own subclasses for function calls, this should be the name of the function that corresponds to the subclass, for example, FA12TezosMint.entrypoint is set to the “mint” string. Then, save() can provision function from that.

contract_name

In your own subclasses for contract transactions, this should be the name of the file that contains smart contract code, without extension. The file must be in the sub-directory contracts of the django app of the model.

exception DoesNotExist

exception MultipleObjectsReturned

contract_subclass()

Return the subclass of the .contract relation.

dependency_add(transaction)

Add a transaction that must be deployed before this one.

Parameters:

transaction – The transaction that must be deployed before this one.

dependency_get()

Return the transaction that must be deployed before this one.

dependency_graph()

Return the dependency graph this transaction is part of, if any.

deploy()

Deploy the transaction.

Wrapper around the djwebdapp.provider.Provider.deploy() method to deploy this trasnsaction.

In case of exception, it will log the exception, set last_fail, and count the number of deploy attempts in history.

If the deploy attempts count is above the max_fails field, then set state to aborted, otherwise, set it to retry.

get_args()

Return the arguments of the transaction.

normalize()

Method invoked when normalizing a transaction.

By default, this relies on normalizer_class

normalizer_get()

Return the normalizer class for this transaction.

property provider

Return the blockchain’s Provider.

save(*args, **kwargs)

Save the transaction in the database.

Sets kind based on the attributes of this transaction and blockchain from the sender automatically.

Also, provision function and contract from entrypoint and target_contract.

state_set(state)

Set state attribute and save it to the history.

TransactionManager

class djwebdapp.models.TransactionManager(*args, **kwargs)

Manager for the Transaction model.

This Model Manager overrides get_or_create() and update_or_create() to handle parent foreign keys dynamically.

find_or_create(lookup_attributes, defaults=None)

Find or create a transaction model.

get_or_create(*args, **kwargs)

Same as Django’s, with dynamic parent fk handled.

property parent_fk_column

Return the name of the foreign key to the parent.

update_or_create(*args, **kwargs)

Same as Django’s, with dynamic parent fk handled.

Dependency

class djwebdapp.models.Dependency(*args, **kwargs)

A dependency between two transactions.

When a transaction is deployed, it is checked if it has a dependency. If it does, the transaction is not deployed, but the dependency is checked instead. If the dependency is deployed, the transaction is deployed. Otherwise, the transaction is not.

dependent

The Transaction that depends on the dependency one.

dependency

The Transaction that is required to be deployed before the dependent one.

graph

The Transaction that this graph was created for. This is used for performance reasons, to not have to load the full dependency table for every transaction.

created_at

The time the dependency was created.

updated_at

The time the dependency was updated.

exception DoesNotExist

exception MultipleObjectsReturned

Provider

class djwebdapp.provider.Provider(blockchain=None, wallet=None)

Base Provider class, encapsulates business logic with blockchains.

Instanciating a Provider requires either a blockchain or a wallet argument.

Warning

Do not use this class directly, it is meant to be sub-classed for each blockchain type.

Parameters:

• blockchain – Blockchain object to instanciate the Provider with, in which case the Python client for the blockchain will use its default account.

• wallet – Account object to bind the provider with, in which case the secret_key must be set in the Account.

Note

You don’t need to pass both wallet and blockchain arguments, the provider will instanciate with the blockchain attribute of the wallet argument if any.

blockchain

Blockchain this provider was instanciated for.

wallet

Account this provider was instanciated for, if any.

Danger

When instanciating a provider with a wallet, make sure the Account has a secret key! Otherwise, the blockchain client will not be able to send any transaction!

transaction_class

Transaction subclass this provider works with. For example, TezosTransaction if it’s a tezos provider, or a EthereumTransaction if it’s an ethereum provider. This is supposed to be set as a class attribute by the provider subclass.

exclude_states

States to exclude when searching for transactions to deploy.

property client

Cached result of get_client()

deploy(transaction)

Deploy a given Transaction object.

download(target: str)

Download a contract history from the configured indexer.

This will use an indexer such as etherscan or tzkt to download the history from a web-API rather than by indexing the blockchain which could take a really long while for large contracts.

Parameters:

target – String address of the contract to download history for.

generate_secret_key()

Generate a secret key.

Raises NotImplemented in base Provider class.

get_balance(address=None)

Query the blockchain and return the balance of an address.

address

Address to get the balance of, use the current client address by default.

get_client(wallet=None)

Return the Python client that provider encapsulates.

Parameters:

wallet – Account object to use, note that it must have a secret_key.

property head

Return the current block number.

Raises NotImplemented in base Provider class.

index()

Index the blockchain.

Return if reorg() returns True.

Iterate over each level from the last indexed level in the djwebdapp.models.Blockchain.index_level column (or 0) up to the current head level. Call index_level() for each level.

index_init()

Query the database for transactions hashes and contract addresses to index in index()

Provisions

index_level(level: int)

Index a given block level.

Left to implement in new provider subclasses.

normalize()

Run normalize() on all un-normalized transactions.

Call normalize() on each transaction that has not been normalized.

Internal transactions are normalized after their caller is normalized.

reorg()

Handle reorg if necessary.

Compare the head level with the last indexed level, if it’s superior then consider a reorg happened on the blockchain.

In this case, empty the level, hash, and address of every Transaction in DB which has a level greater than or equal to the current head level, and set their state to deleted.

spool()

Deploy the next transaction of any kind and return it.

It checks for the next transaction with the following logic:

• spool_transfers(): is there any new transfer to deploy?

• spool_contracts(): is there any new contract to deploy from an account with balance?

spool_calls()

Return the calls to deploy in spool().

Return a QuerySet of transaction_class objects of this blockchain which:

• are of kind function

• have no hash

• are related to a contract which does have an address

• which state is not in exclude_states,

• which sender Account have not deployed to the blockchain during this level according to head and djwebdapp.models.Account.last_level

• which sender has balance above 0

• ordered by created_at ascending order, so that it gets the oldest first.

spool_contracts()

Return the contracts to deploy, used by spool().

Return a QuerySet of transaction_class objects of this blockchain which:

• are of kind contract

• have no hash

• have code according to has_code, so that we can actually deploy it

• have no address

• which state is not in exclude_states,

• which sender Account have not deployed to the blockchain during this level according to head and djwebdapp.models.Account.last_level

• which sender has balance above 0

• ordered by created_at ascending order, so that it gets the oldest first.

spool_transfers()

Return the transfers to deploy, used by spool().

Return a QuerySet of transaction_class objects of this blockchain which:

• are of kind transfer

• have no hash

• which state is not in exclude_states,

• which sender Account have not deployed to the blockchain during this level according to head and djwebdapp.models.Account.last_level

• which sender has balance above 0

• ordered by created_at ascending order, so that it gets the oldest first.

class djwebdapp.provider.Success(blockchain=None, wallet=None)

get_balance(address=None)

Query the blockchain and return the balance of an address.

address

Address to get the balance of, use the current client address by default.

djwebdapp.provider.call_deploy(arg)

Wrap a call in a try/except with logging.

Parameters:

arg – Tuple of (logger, call)

djwebdapp.provider.get_calls_distinct_sender(calls_query_set, n_calls)

Given a QS of calls, return a list of calls with distinct senders.

Parameters:

• calls_query_set – Queryset of Calls

• n_calls – Number of calls to return

Normalizer

Normalizer classes are optionnal helpers to easy contract indexation.

class djwebdapp.normalizers.Normalizer

Base Normalizer class.

Exceptions

exception djwebdapp.exceptions.BaseException

Base exception class for all exceptions of this package.

exception djwebdapp.exceptions.PermanentError

Raised when a transaction can not be deployed.

exception djwebdapp.exceptions.TemporaryError

Raised when a transaction has not been deployed.

Management commands

spool

class djwebdapp.management.commands.spool.Command(stdout=None, stderr=None, no_color=False, force_color=False)

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

index

class djwebdapp.management.commands.index.Command(stdout=None, stderr=None, no_color=False, force_color=False)

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

normalize

class djwebdapp.management.commands.normalize.Command(stdout=None, stderr=None, no_color=False, force_color=False)

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

refresh_balances

class djwebdapp.management.commands.refresh_balances.Command(stdout=None, stderr=None, no_color=False, force_color=False)

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

history_download

class djwebdapp.management.commands.history_download.Command(stdout=None, stderr=None, no_color=False, force_color=False)

add_arguments(parser)

Entry point for subclassed commands to add custom arguments.

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.