algorand-verifier-lib 0.42

No project description provided

Algorand Verifier Library

Python library for verifying on-chain Algorand applications with source code.

Usage

Install using pip: pip install algorand_verifier_lib

Using helper functions with PureStake API

In the most general case, the simplest way to use hte library is to use functions from helpers.py with the PureStake API.

First set the PURESTAKE_API_KEY envvar either on your environment or in a .env file in the working directory for your app:

export PURESTAKE_API_KEY=<YOUR_API_KEY>
echo PURESTAKE_API_KEY=<YOUR_API_KEY> >> .env

Then in Python code:

from algorand_verifier_lib import teal_urls_match_app_id

app_id = "552635992"
matches = teal_urls_match_app_id(https://github.com/tinymanorg/tinyman-contracts-v1/blob/13acadd1a619d0fcafadd6f6c489a906bf347484/contracts/validator_approval.teal", "https://github.com/tinymanorg/tinyman-contracts-v1/blob/13acadd1a619d0fcafadd6f6c489a906bf347484/contracts/validator_clear_state.teal", app_id)
if matches:
  print(f"The on-chain algorand application ID {app_id} matches the provided source code")
else:
  print(f"The on-chain algorand application ID {app_id} does NOT match the provided source code")

Using AlgoApiClient With Custom API Endpoints

If your use-case requires more control, such as using a custom API endpoint for an Algorand node running on your local machine etc.

Against an API that requires an API key to be set:

from algorand_verifier_lib import AlgoApiClient, OpenSourceParser

parser = OpenSourceParser()
approval_source = parser.source_from_any("https://github.com/approval_teal")
clear_state_source = parser.source_from_any("https://github.com/clear_state_teal")

app_id = "552635992"
client = AlgoApiClient("https://mainnet.api", "<YOUR_API_KEY>")
matches = client.compare_teal_to_app(approval_source, clear_state_source, app_id)
if matches:
  print("Successful match")

If you're using an API that doesn't require an API key, initialise the AlgoApiClient with an empty key:

client = AlgoApiClient("https://mainnet.api", "")

Technical Design

The library is based on 3 parts with different responsibilities:

• algo_api_client.py contains the logic for interacting with the Algorand API endpoints and some of the lower-level verification logic e.g. compare_teal_to_app. Should be used directly when extra control is required such as setting the API base URL(e.g. https://mainnet-api.com, https://testnet-api.com) or making custom API calls.
• open_source_parser.py is responsible for parsing out source code from given URLs, for example converting a normal Github link to a raw link containing only the source code text that can then be downloaded by the library.
• helpers.py provides endpoint, most-general case usage functions that combine both algo_api_client.py and open_source_parser.py. It is for when the caller does not require much control such as teal_urls_match_app_id, which will use the PureStake API on the Algorand mainnet to verify a TEAL contract. The Django webapp in this repo only uses functions from helpers.py currently as it doesn't require any special API settings etc.

Testing

The tests for the library use the PureStake API and make real API calls so they can take some time, but is usually under 10 seconds. The tests will run with Github Actions CI on every push, but it sometimes may be required to run the tests locally.

Assuming you are in the algorand_verifier_lib lib directory that contains this README.md:

export PURESTAKE_API_KEY=<YOUR_API_KEY>

python -m venv venv
. venv/bin/activate
pip install -r requirements.txt
python -m pytest src/algorand_verifier_lib

If any errors are encountered related to 403 HTTP authentication etc., ensure that the PURESTAKE_API_KEY envvar is correct.

Releasing New Versions

Documentation

Create a virtualenv and install the normal requirements, and also pdoc:

python -m venv venv
. venv/bin/activate
pip install -r requirements.txt
pip install pdoc

In the algorand_verifier_lib directory the src code files can be referenced to generate the documentation:

pdoc src/algorand_verifier_lib/*

This will open your browser at localhost:8080 with the libraries documentation visible.