`dapp.config` –Module with Permission dApp constants

Module with Permission dApp constants.

`dapp.contract` – Permission dApp smart contract module

Permission dApp smart contract implemented with Algorand Python (puyapy).

class contract.PermissionDApp(*args: Any, **kwargs: dict[str, Any])

Bases: ARC4Contract

A permission-based dApp that allows only the creator to manage boxes.

create_application() → None: Handles the application creation. This method is called only once, when the contract is deployed.

delete_application() → None: Allows only the creator to delete the application.

delete_box(box_name: DynamicBytes) → None

Delete a box. Only the creator can call this method.

Args:: box_name: The name of the box to delete (should be 32 bytes)

global_state_types = {}

update_application() → None: Allows only the creator to update the application.

write_box(box_name: DynamicBytes, value: String) → None

Write a value to a box. Only the creator can call this method.

Args:: box_name: The name of the box (should be 32 bytes) value: The string value to write to the box

`dapp.deploy` – Module with functions for deploying Permission dApp smart contract to blockchain

Module with functions for deploying Permission dApp smart contract to blockchain.

deploy.deploy_app(network='testnet')

Compile Permisssion dApp smart contract, deploy it, and update the artifact.

This function orchestrates the deployment process by: 1. Compiling the TEAL approval and clear programs 2. Creating a new application on the specified network 3. Capturing the new app ID and the network’s genesis hash 4. Updating the ARC-56 JSON artifact with the new network information

Parameters:

network (str) – network to deploy to (e.g., “testnet”)

Variables:

env – environment variables collection
dapp_name – name of the smart contract application
client – Algorand Node client
creator_private_key – private key of the application creator
approval_program_source – approval program source code
clear_program_source – clear program source code
contract_json – ARC-56 smart contract specification
approval_program – compiled approval program
clear_program – compiled clear program
app_id – ID of the newly created application
genesis_hash – genesis hash of the network

Returns:

ID of the newly created application

Return type:

int

deploy.fund_app(app_id, network, amount=1000000)

Fund the application escrow account with 0.2 Algo.

Creates an Algod client and sends a payment transaction from the creator’s account to the application escrow address. Waits for confirmation before returning.

Parameters:

app_id (int) – The smart contract application ID.
network (str) – Network where the app is deployed (e.g., "testnet").

Variables:

amount – amount in microAlgos to send to application’s escrow
env – environment variables collection
client – Algorand Node client instance
creator_private_key – The private key of the application creator
sender – Derived Algorand wallet address from private key
app_address – Application escrow account address
sp – suggested transaction params
txn – payment transaction params
signed_txn – signed transaction instance
tx_id – transaction’s unique identifier

`dapp.foundation` – Module with functions for importing DAO docs and staking data

Module with functions for importing DAO docs and staking data.

foundation.check_and_update_permission_dapp_boxes(network='testnet')

Check and update boxes if staking and/or subscription values have changed.

Parameters:

network (str) – network to deploy to (e.g., “testnet”)

Variables:

env – environment variables collection
client – Algorand Node client instance
mainnet_client – Algorand Mainnet Node client instance
app_id – Pewrmission dApp identifier
writing_parameters – instances sneeded for writing boxes to blockchain
subscriptions – Subtopia subscribers addresses and related tiers’ values
stakings – collection of all governance staking addresses and related amounts
permissions – collection of addresses and related votes and permission values

foundation.prepare_and_write_data(network='testnet')

Collect and write collection of DAO addresses and related values.

Parameters:

network (str) – network to deploy to (e.g., “testnet”)

Variables:

env – environment variables collection
client – Algorand Node client instance
data – collection of addresses and related permission and votes values
writing_parameters – instances sneeded for writing boxes to blockchain

`dapp.helpers` – Permission dApp helper functions module

Module with Permission dApp helpers functions.

helpers.app_schemas(contract_json)

Return instances of state schemas for smart contract’s global and local apps.

Parameters:

contract_json (dict) – full path to smart contract’s JSON file

Variables:

schema – smart contract’s schema
global_schema – smart contract’s global schema
local_schema – smart contract’s local schema
local_bytes – total number of local bytes states
global_ints – total number of global uint states
global_bytes – total number of global bytes states

Returns:

two-tuple

helpers.box_name_from_address(address)

Return string representation of base64 encoded public Algorand address.

Parameters:: address (bytes) – governance seat address
Returns:: str

helpers.box_writing_parameters(env, network='testnet')

Instantiate and return arguments needed for writing boxes to blockchain.

Parameters:

env (dict) – environment variables collection
network (str) – network suffix for environment variable keys

Variables:

creator_private_key – application creator’s base64 encoded private key
sender – application caller’s address
signer – application caller’s signer instance
contract – application caller’s address

Returns:

dict

helpers.calculate_votes_and_permission(values)

Calculate and update votes and permission values for all addresses in data.

Parameters:

data (dict) – collection of addresses and related permission and votes values

Variables:

address – currently processed governance seat address
values – collection of integer values
docs_permission – total permission from foundation and staking documents
votes – total votes from foundation and staking documents
subscription_permission – permission value from address’ subcription tier
staking_permission – permission value from address’ current governance staking

Returns:

two-tuple

helpers.compile_program(client, source_code)

Collect and return collection of addresses and related values.

Parameters:

client (AlgodClient) – Algorand Node client instance

Variables:

source_code – approval/clear program code
compile_response – compilation response from Node instance

Returns:

str

helpers.deserialize_values_data(data)

Return collection of integer values deserialized from base64 encoded data.

Parameters:

data (str) – base64 encoded values collection

Variables:

decoded – base64 decoded values collection
offset – current value’s offset/position in encoded data
length – current value’s size in bytes

Returns:

list

helpers.environment_variables()

Return collection of required environment variables.

Returns:: dict

helpers.governance_staking_addresses(staking_app_id=None, staking_min_round=None)

Return all addresses involved in the staking program run by staking_app_id.

Parameters:

staking_app_id (int) – Algorand application identifier

Variables:

addresses – collection of public Algorand adresses
indexer_client – Algorand Indexer client instance
params – collection of arguments provided to Indexer method
transaction – currently processed application transaction instance

Returns:

set

helpers.load_contract(dapp_name='PermissionDApp')

Load from disk, instantiate and return Permission dApp smart contract object.

Variables:: contract_json – full path to Permission dApp smart contract file
Returns:: Contract

helpers.pause(seconds=1)

Sleep for provided number of seconds.

Parameters:: seconds (int) – number of seconds to pause

helpers.permission_dapp_id(network='testnet')

Return Permission dApp identifier for provided network.

Parameters:: network (str) – network to check the dapp ID for (e.g., “testnet”)
Returns:: int

helpers.permission_for_amount(amount)

Calculate and return permission value from provided amount.

Parameters:

amount (int) – amount in ASASTATS to calculate permission value for
boundary (int) – currently processed minimum staking amount boundary
votes (float) – number of votes for currently processed boundary

Returns:

int

helpers.private_key_from_mnemonic(passphrase)

Return base64 encoded private key created from provided mnemonic passphrase.

Parameters:: passphrase (str) – collection of English words separated by spaces
Returns:: str

helpers.read_json(filename)

Return collection of key and values created from provided filename JSON file.

Parameters:: filename (pathlib.Path) – full path to JSON file
Returns:: dict

helpers.serialize_values(values)

Return base64 encoded data serialized from values collection of integers.

Parameters:

values (list) – collection of integer values to serialize

Variables:

_bytes – serialized values collection
position – current byte’s position in serialized data
val – current byte’s value in serialized data

Returns:

str

helpers.wait_for_confirmation(client, txid)

Wait for a blockchain transaction to be confirmed.

Polls Algorand node until the transaction referenced by txid is confirmed in a round. Prints waiting messages until confirmation then returns full pending transaction information.

Parameters:

client (AlgodClient) – Algorand Node client instance
txid (str) – blockchain transaction ID

Returns:

pending transaction info including confirmed round

Return type:

dict

`dapp.network` – Module with functions for retrieving and saving blockchain data

Module with functions for retrieving and saving blockchain data.

network.check_and_update_changed_subscriptions_and_staking(client, app_id, writing_parameters, permissions, subscriptions, stakings)

Check and update boxes for address with changed subscriptions and staking.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – currently processed subscription tier app
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
permissions (dict) – collection of addresses and related votes and permission values
subscriptions (dict) – Subtopia subscribers addresses and related tiers’ values
stakings (dict) – collection of all governance staking addresses and related amounts

Variables:

address – currently processed address
values – currently processed address’ values collection
update – value indicating if update is needed or not
staking_amount – current staking amount for currently processed address
subscription_values – collection of amount and permission pairs
subscribed_amuunt – current subscribed amount for currently processed address

network.check_and_update_new_stakers(client, app_id, writing_parameters, permissions, stakings)

Check and update boxes for completely new staking addresses.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – currently processed subscription tier app
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
permissions (dict) – collection of addresses and related votes and permission values
stakings (dict) – collection of all governance staking addresses and related amounts

Variables:

new_stakers – collection of new staking addresses with related values
address – currently processed staking address
amount – staking amount
values – collection of votes and permissions

network.check_and_update_new_subscribers(client, app_id, writing_parameters, permissions, subscriptions)

Check and update boxes for completely new subscriber addresses.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – currently processed subscription tier app
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
permissions (dict) – collection of addresses and related votes and permission values
subscriptions (dict) – Subtopia subscribers addresses and related tiers’ values

Variables:

new_subscribers – collection of new subscribers with related values
address – currently processed staking address
subscription_values – collection of amount and permission pairs
values – collection of votes and permissions

network.create_app(client, private_key, approval_program, clear_program, contract_json)

Create a new smart contract application on the Algorand blockchain.

Builds and submits an ApplicationCreate transaction using compiled approval and clear programs. Waits for confirmation and returns the resulting app-id and genesis hash.

Parameters:

client (AlgodClient) – Algorand Node client instance.
private_key (str) – Creator’s private key used to sign the transaction.
approval_program (bytes) – Compiled TEAL approval program.
clear_program (bytes) – Compiled TEAL clear program.
contract_json (dict) – ARC-56 smart contract specification.

Returns:

A tuple containing the newly created application ID and genesis hash.

Return type:

tuple[int, str]

network.current_governance_staking_for_address(client, address, staking_key=None)

Return staking amount for address from Cometa’s staking program.

NOTE: checking is currently suppressed by default

Parameters:

client (AlgodClient) – Algorand Node client instance
address (str) – governance seat address associated with the box
staking_key (str) – staking program’s staking key

Variables:

state – staking application’s local state object

Returns:

int

network.delete_app(client, private_key, index)

Delete an existing application on the Algorand blockchain.

Builds and submits an ApplicationDelete transaction, waits for confirmation, and prints application id removed from the blockchain.

Parameters:

client (AlgodClient) – Algorand Node client instance
private_key (str) – application’s creator private key used to sign transaction
index (int) – application id to delete

Returns:

None

network.delete_box(client, app_id, writing_parameters, address)

Delete box owned by app_id defined by provided address.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – Permission dApp identifier
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
address (str) – governance seat address associated with the box

Variables:

atc – transaction composer instance
box_name – base64 encoded box name
response – application call’s response

network.deserialized_permission_dapp_box_value(client, app_id, box_name)

Fetch box_name value and return deserialized values from it.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – Permission dApp identifier
box_name (str) – base64 encoded box name

Variables:

response – fetch application box call’s response

Returns:

list

network.fetch_subscriptions_for_address(client, address)

Return collection of all subscriptions for provided address.

Box value contains the following uints: (tier_asset_id, 2, subscription_start, subscription_end, subscription_duration)

Parameters:

client (AlgodClient) – Algorand Node client instance
address (str) – currently processed box’s user address

Variables:

subscriptions – collection of tier names and related expiration timestamps
app_id – currently processed subscription tier app
tier_name – subscription tier name
box_name – currently processed box’s name
response – user’s box response instance
hexed – user box value’s hexadecimal string representation
start – starting position of subscription’s end value
subscription_end – timestamp when subscription expires

Returns:

dict

network.fetch_subscriptions_from_boxes(client)

Return collection of all subscribed addresses with related subscription values.

Box value contains the following uints: (tier_asset_id, 2, subscription_start, subscription_end, subscription_duration)

Parameters:

client (AlgodClient) – Algorand Node client instance

Variables:

subscriptions – Subtopia subscribers addresses and related tiers’ values
app_id – currently processed subscription tier app
amount – currently processed app’s subscription amount
permission – currently processed subscription app’s permission
boxes – collection of currently processed app’s boxes fetched from Node
box_name – currently processed box’s name
address – currently processed box’s user address
response – user’s box response instance
hexed – user box value’s hexadecimal string representation
start – starting position of subscription’s end value
subscription_end – timestamp when subscription expires

Returns:

dict

network.permission_dapp_values_from_boxes(client, app_id)

Return collection of all addresses with related votes and permission values.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – Permission dApp identifier

Variables:

permissions – collection of addresses and related votes and permission values
boxes – collection of Pewrmission dApp’s boxes fetched from Node
box_name – currently processed box’s name
address – currently processed box’s user address
values – collection of deserialized values for currently processed address

Returns:

dict

network.write_box(client, app_id, writing_parameters, address, value)

Write value to the box owned by app_id defined by provided address.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – Permission dApp identifier
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
address (str) – governance seat address associated with the box
value (str) – serialized base64 encoded values collection

Variables:

atc – transaction composer instance
box_name – base64 encoded box name
response – application call’s response

network.write_foundation_boxes(client, app_id, writing_parameters, data)

Write to the boxes owned by app_id values extracted from provided data.

Parameters:

client (AlgodClient) – Algorand Node client instance
app_id (int) – Permission dApp identifier
writing_parameters (dict) – instances sneeded for writing boxes to blockchain
data (dict) – collection of addresses and associated integer values

Variables:

address – currently processed governance seat address
values – currently processed integer values collection
value – currently processed serialized base64 encoded values collection

`dapp.utils` – Permission dApp utility functions module

Module with smart contract’s utility functions .

utils.check_test_box(app_id_str)

Check and display test box contents for a given application ID.

Decodes and displays box contents for testing purposes, showing: - The address associated with each box - Hexadecimal representation of box values - Parsed integer values in 16-byte chunks

Parameters:

app_id_str (str) – application ID as string

Variables:

app_id – application ID converted to integer
env – environment variables collection
client – Algorand Node client instance
boxes – collection of boxes associated with the application
box_name – base64 decoded box name
address – Algorand address derived from box name
response – box value response from the node
hexed – hexadecimal representation of box value

utils.delete_boxes()

Delete all boxes from the Permission dApp on testnet.

This function: 1. Retrieves environment variables and creates an Algod client 2. Gets the application ID for the Permission dApp on testnet 3. Fetches all boxes associated with the application 4. Deletes each box by encoding the box name to an address

Variables:

env – environment variables collection
app_id – Permission dApp application ID on testnet
client – Algorand Node client instance
writing_parameters – transaction parameters for box operations
boxes – collection of boxes associated with the application
box_name – base64 decoded box name
address – Algorand address derived from box name

utils.print_box_values(network='testnet')

Print all box values from the Permission dApp in sorted order.

Retrieves and displays permission values from application boxes, sorted by the second value in descending order. Shows a message if no boxes are found.

Parameters:

network (str) – network to query (e.g., “testnet”)

Variables:

env – environment variables collection
client – Algorand Node client instance
app_id – Permission dApp application ID
permissions – dictionary of address to permission values

`dapp.DAO` – ASA Stats DAO governors selection documents directory

`dapp.tests` – Permission dApp unit-tests package

Initialization module for Permission dApp unit tests.

dapp.config –Module with Permission dApp constants

dapp.contract – Permission dApp smart contract module

dapp.deploy – Module with functions for deploying Permission dApp smart contract to blockchain

dapp.foundation – Module with functions for importing DAO docs and staking data

dapp.helpers – Permission dApp helper functions module

dapp.network – Module with functions for retrieving and saving blockchain data

dapp.utils – Permission dApp utility functions module

dapp.DAO – ASA Stats DAO governors selection documents directory

dapp.tests – Permission dApp unit-tests package

`dapp.config` –Module with Permission dApp constants

`dapp.contract` – Permission dApp smart contract module

`dapp.deploy` – Module with functions for deploying Permission dApp smart contract to blockchain

`dapp.foundation` – Module with functions for importing DAO docs and staking data

`dapp.helpers` – Permission dApp helper functions module

`dapp.network` – Module with functions for retrieving and saving blockchain data

`dapp.utils` – Permission dApp utility functions module

`dapp.DAO` – ASA Stats DAO governors selection documents directory

`dapp.tests` – Permission dApp unit-tests package