colossus_sdk 0.1.2

A Python SDK for interacting with the Colossus API

Colossus Staking Python SDK

Welcome to the Colossus Staking Python SDK - your definitive toolkit for staking and delegation. This SDK provides a streamlined experience for initiating staking flows, handling delegation, and managing signed transactions, ensuring seamless and secure integration to the POS networks.

• Colossus Staking Python SDK
  • Build the Colossus SDK Application
    • Prerequisites for Colossus SDK
    • Installing Colossus SDK Dependencies
  • Running the Colossus SDK Application
    • Starting the Colossus API Server
    • Running SDK Testing Tool
    • Understanding SDK Output Data
  • SDK Testing Procedures
    • Testing Colossus SDK Server with curl Commands
    • Executing Automated Tests for the SDK
      • Running a Single Test File
    • Performing Coverage Analysis for SDK Tests
    • Generating Test Coverage Reports for the SDK
  • MongoDB Command Reference for Staking Data Management
    • Accessing and Querying the Staking Database
• Building and Deploying the Colossus SDK
  • Configuring pyproject.toml for Colossus SDK
  • Building the Colossus SDK Package
  • Publishing the Colossus SDK to PyPI
  • Version Control Tagging for SDK Releases
• Using Poetry's Built-in Authentication:
  • Environment Variables:
  • Keyring Support:

---

Build the Colossus SDK Application

Prerequisites for Colossus SDK

• Python: Version 3.11 or higher.
• Poetry: Dependency management tool for Python.

Installing Colossus SDK Dependencies

Before building the program, ensure you have the following prerequisites:

1. Navigate to the project directory:

   cd colossus_sdk
   

2. Setup Environment:

   Create a virtual environment and activate it:

   python3.11 -m venv venv
   source venv/bin/activate
   

3. Install the necessary dependencies using Poetry:

   poetry install
   

Running the Colossus SDK Application

Starting the Colossus API Server

To start the server and import validator keys using mnemonics, use the following command:

poetry run python colossus_sdk/endpoint_server.py

Running SDK Testing Tool

poetry run python colossus_sdk/tester.py

Understanding SDK Output Data

poetry run python colossus_sdk/tester.py

Flow ID: ['2d514903-2a09-41d6-938d-65965c0d7507']
Delegated State: delegated
Transaction State: broadcasted

SDK Testing Procedures

Testing Colossus SDK Server with curl Commands

To test the API endpoints, you can use the curl command-line tool. Here are some example commands:

1. Test the Create Staking Flow Endpoint:

   curl -X POST -H "Content-Type: application/json" \
     -d '{"flow": {"network_code": "cosmos", "chain_code": "testnet", "operation": "staking"}}' \
     http://127.0.0.1:5000/api/v1/flows
   

2. Test the Delegate Endpoint (Replace {flow_id} with the actual flow ID):

   curl -X PUT -H "Content-Type: application/json" \
     -d '{"name": "create_delegate_tx", "inputs": {"delegator_address": "your_address", "validator_address": "validator_address", "amount": 100}}' \
     http://127.0.0.1:5000/api/v1/flows/{flow_id}/next
   

3. Test the Signed Delegate Endpoint (Replace {flow_id} with the actual flow ID):

   curl -X PUT -H "Content-Type: application/json" \
     -d '{"name": "sign_delegate_tx", "inputs": {"transaction_payload": "your_payload"}, "signatures": ["signature1", "signature2"]}' \
     http://127.0.0.1:5000/api/v1/flows/{flow_id}/next
   

Replace placeholders like your_address, validator_address, your_payload, etc., with actual values when executing the commands.

---

Executing Automated Tests for the SDK

To execute your tests, you can use the following command:

poetry run pytest

# or

poetry run pytest tests/test_colossus_client.py

Or, if you are using unittest and your test files are named in the pattern test_*.py, you can use:

poetry run python -m unittest discover

Running a Single Test File

To run a specific test file, simply provide the path to the file. For example:

poetry run pytest tests/test_my_feature.py

Performing Coverage Analysis for SDK Tests

Run tests with coverage using the following command:

poetry run pytest --cov=colossus_sdk/.

Generating Test Coverage Reports for the SDK

Terminal Report:

poetry run pytest --cov=colossus_sdk/. --cov-report=term

Create HTML Report:

poetry run pytest --cov=colossus_sdk/. --cov-report=xml

XML Report:

poetry run pytest --cov=your_package_name --cov-report=xml

---

MongoDB Command Reference for Staking Data Management

This section outlines the MongoDB commands used for querying the staking database, specifically within the flows collection.

Accessing and Querying the Staking Database

First, Start mongo cli:

./mongosh

Switch to the staking database:

use staking

Retrieve and Display All Documents in flows Collection

This command fetches all documents from the flows collection and displays them in a formatted manner.

db.flows.find().pretty()

Find a Specific Document by Flow ID

Replace your_flow_id with the actual ID of the flow you want to query.

db.flows.find({"flow_id": "your_flow_id"}).pretty()

Example using a specific flow ID:

db.flows.find({"flow_id": "b2c4c9c9-a6ef-46f7-b1a4-e3aebd9ba84b"}).pretty()

Drop the Collection

Example to drop the flows collection:

db.flows.drop()

---

Building and Deploying the Colossus SDK

Configuring pyproject.toml for Colossus SDK

Ensure your pyproject.toml file is correctly set up with all necessary information. This includes the package name, version, description, dependencies, and any other relevant metadata. Here's an example template:

[tool.poetry]
name = "colossus-sdk"
version = "0.1.0"
description = "A Python SDK for interacting with the Colossus API"
authors = ["Your Name <[e-mail]>"]

[tool.poetry.dependencies]
python = "^3.11"

[tool.poetry.dev-dependencies]
pytest = "^7.4.3"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Building the Colossus SDK Package

To build the package, execute the following command:

poetry build

This command will generate a .tar.gz archive and a .whl file in the dist directory.

Publishing the Colossus SDK to PyPI

To publish your package to PyPI (Python Package Index), create a account on PyPI.

Once the account is created, publish your package using:

poetry publish

This command will prompt you for your PyPI username and password. If you are using a CI/CD pipeline, you can also automate this step using API tokens.

Version Control Tagging for SDK Releases

After deploying your package, tag the commit and push the tag to your remote repository:

git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0

---

Using Poetry's Built-in Authentication:

Run poetry config http-basic.pypi username password in your terminal.

This command stores your credentials securely in Poetry's configuration.

Replace username and password with your actual PyPI credentials. If you're using a token, your username will be token, and your password will be the token value.

Environment Variables:

You can also set your credentials as environment variables. For example, set POETRY_PYPI_TOKEN_PYPI to your PyPI token. This is a secure way to handle credentials, especially in CI/CD pipelines.

Keyring Support:

Poetry can integrate with the system's keyring to store credentials securely. First, install a keyring backend if you don't have one (like keyring package in Python). Store your credentials in the keyring, and Poetry will automatically use them when needed.