Development Guidelines

May 18, 2026 · View on GitHub

Getting the Source
Setting up a New Development Environment
Development
Generating python types from Cosmos SDK protobuf schemas
Setting up a local Fetchai node
Running a local Fetchai node in docker
Contributing

Getting the Source

Fork the repository.

Clone your fork of the repository:

git clone git@github.com:<github username>/cosmpy.git

Define an upstream remote pointing back to the main CosmPy repository:
```
git remote add upstream https://github.com/fetchai/cosmpy.git
```

Setting up a New Development Environment

Ensure you have Python (version 3.10, 3.11, 3.12 or 3.13) and poetry.
```
make new-env
```
This will create a new virtual environment using poetry with the project and all the development dependencies installed.

We use poetry to manage dependencies. All python specific dependencies are specified in pyproject.toml and installed with the library.

You can have more control on the installed dependencies by leveraging poetry's features.
```
poetry shell
```
To enter the virtual environment.

To update the protobuf schemas and generate their associated python types, you will need Google Protocol Buffers.

Development

General code quality checks

To run general code quality checkers, formatters and linters:

```
 make lint
```
Automatically formats your code and sorts your imports, checks your code's quality and scans for any unused code.
```
 make mypy
```
Statically checks the correctness of the types.
```
 make pylint
```
Analyses the quality of your code.
```
 make security
```
Checks the code for known vulnerabilities and common security issues.
```
 make clean
```
Cleans your development environment and deletes temporary files and directories.

Updating documentation

We use mkdocs and material-for-mkdocs for static documentation pages. To make changes to the documentation:

```
 make docs-live
```
This starts a live-reloading docs server on localhost which you can access by going to http://127.0.0.1:8000/ in your browser. Making changes to the documentation automatically reloads this page, showing you the latest changes. To create a new documentation page, add a markdown file under /docs/ and add a reference to this page in mkdocs.yml under nav.

Updating API documentation

If you've made changes to the core cosmpy package that affects the public API:

```
 make generate-api-docs
```
This regenerates the API docs. If pages are added/deleted, or there are changes in their structure, these need to be reflected manually in the nav section of mkdocs.yaml.

Updating dependencies

We use poetry and pyproject.toml to manage the project's dependencies.

If you've made any changes to the dependencies (e.g. added/removed dependencies, or updated package version requirements):

```
 poetry lock
```
This re-locks the dependencies. Ensure that the poetry.lock file is pushed into the repository (by default it is).
```
 make liccheck
```
Checks that the licence for the library is correct, taking into account the licences for all dependencies, their dependencies and so forth.

Tests

To test the project, we use pytest. To run the tests:

```
 make test
```
Runs all the tests.
```
 make unit-test
```
Runs all unit tests.
```
 make integration-test
```
Runs all integration tests.
```
 make coverage-report
```
Produces a coverage report (you should run tests using one of the above commands first).

Miscellaneous checks

```
 make copyright-check
```
Checks that all files have the correct copyright header (where applicable).

Generating python types from Cosmos SDK protobuf schemas

This library uses python types which are generated (using Google's Protocol Buffers compiler) from protocol buffer schemas in the Cosmos SDK and WasmD.

When updating the Cosmos-SDK version that is supported by this library (see the version currently used under COSMOS_SDK_VERSION in Makefile), you will need to fetch its corresponding protobuf schemas and generate their associated python types, replacing the existing ones.

Note: This process has to be done only once when the Cosmos-SDK version supported by this library is changed.

Note: To generate python types from Cosmos-SDK protobuf schemas, you will need Google Protocol Buffers compiler. A guide on how to install it can be found here.

To regenerate the protobuf schema files, run the following:
```
make proto
```

Note: For this library to be functional, only python types generated from protobuf schemas are required, not the schema files themselves. The schema files are fetched on-demand only to enable the generation of python types. Therefore, the schema files are intentionally stored as local files and are NOT checked in to this repository to minimise its filesystem footprint.

To set up a local Fetchai node

To set up a local Fetchai node refer to this guide.

To run a local Fetchai node in docker

You require Docker for your platform.

Place the following entrypoint script somewhere in your system (e.g ~/fetchd_docker/fetchd_initialise.sh):

#!/usr/bin/env bash

# variables
export VALIDATOR_KEY_NAME=validator
export BOB_KEY_NAME=bob
export VALIDATOR_MNEMONIC="erase weekend bid boss knee vintage goat syrup use tumble device album fortune water sweet maple kind degree toss owner crane half useless sleep"
export BOB_MNEMONIC="account snack twist chef razor sing gain birth check identify unable vendor model utility fragile stadium turtle sun sail enemy violin either keep fiction"
export PASSWORD="12345678"
export CHAIN_ID=testing
export DENOM_1=stake
export DENOM_2=atestfet
export MONIKER=some-moniker


# Add keys
( echo "$VALIDATOR_MNEMONIC"; echo "$PASSWORD"; echo "$PASSWORD"; ) |fetchd keys add $VALIDATOR_KEY_NAME --recover
( echo "$BOB_MNEMONIC"; echo "$PASSWORD"; ) |fetchd keys add $BOB_KEY_NAME --recover

# Configure node
fetchd init --chain-id=$CHAIN_ID $MONIKER
echo "$PASSWORD" |fetchd add-genesis-account $(fetchd keys show $VALIDATOR_KEY_NAME -a) 100000000000000000000000$DENOM_1
echo "$PASSWORD" |fetchd add-genesis-account $(fetchd keys show $BOB_KEY_NAME -a) 100000000000000000000000$DENOM_2
echo "$PASSWORD" |fetchd gentx $VALIDATOR_KEY_NAME 10000000000000000000000$DENOM_1 --chain-id $CHAIN_ID
fetchd collect-gentxs

# Enable rest-api
sed -i '/^\[api\]$/,/^\[/ s/^enable = false/enable = true/' ~/.fetchd/config/app.toml
sed -i '/^\[api\]$/,/^\[/ s/^swagger = false/swagger = true/' ~/.fetchd/config/app.toml
fetchd start

Execute:
```
docker run -it --rm --entrypoint /scripts/<ENTRYPOINT-SCRIPT-NAME> -p 9090:9090 -p 1317:1317 --mount type=bind,source=<FULL-PATH-TO-ENTRYPOINT-SCRIPT>,destination=/scripts/ <FETCH-IMAGE-TAG>
```
where
- <ENTRYPOINT-SCRIPT-NAME> is the name of the entrypoint script (e.g.fetchd_initialise.sh)
- <PATH-TO-ENTRYPOINT-SCRIPT> is the path to the directory you placed the script (e.g.~/fetchd_docker/),
- <FETCH-IMAGE-TAG> is the tag of the FetchD docker image you want to run (e.g. fetchai/fetchd:0.10.0 for Dorado)

Contributing

For instructions on how to contribute to the project (e.g. creating Pull Requests, commit message convention, etc), see the contributing guide.