# API and CLI for Soroban contracts in Python
This package provide tools to interact with Soroban contracts in Python. The
goal is to provide a simple feature set while not depending on the Rust SDK.
This can be useful in environment where Rust and the SDK might be more
difficult to get working (like a Raspberry Pi).
## Getting started
```
pip install soroban
```
This provides a simple way to call contracts without needing to install the
Rust SDK and is a higher level interface compared to using the Python SDK.
```python
import soroban
soroban.invoke(contract_id="AAAA...", function_name="increment")
```
Identity and Network configurations are automatically pulled from the global
or local configuration.
It also provides a CLI
```shell
soroban invoke C... version --source-account=...
```
## Usage
The main feature is to be able to call a Soroban contract function: `soroban.invoke`.
```python
import soroban
soroban.invoke(contract_id="AAAA...", function_name="increment")
```
It also supports passing arguments as a list of `stellar_sdk.SCVal`. This list
can be easily generated
```python
import json
import soroban
args = json.load(...)
args = soroban.Parameters(args=args).model_dump()
soroban.invoke(contract_id="AAAA...", function_name="init", args=args)
```
The following JSON syntax is supported. Note that vectors are also supported:
```json
[
{
"name": "issuer",
"type": "address",
"value": "C..."
},
{
"name": "distributor",
"type": "int128",
"value": 10
},
{
"name": "claimants",
"type": "vec",
"value": [
{
"type": "uint32",
"value": 12
},
{
"type": "int64",
"value": 20
}
]
}
]
```
A few helper functions are also provided:
- `soroban.create_account`: create and fund an account from a source account;
- `soroban.create_asset`: create an asset using the classical issuer/distributor model.
## Configuration
The source account and the network to use are set by instantiating `soroban.Identity`
and `soroban.NetworkConfig`, respectively:
```python
import soroban
identity = soroban.Identity()
network = soroban.NetworkConfig()
```
In both cases, the configuration can be set by either adjusting init arguments,
setting up environment variables or using configuration files in toml.
The default path for `soroban.Identity` is `identity.toml` and for `soroban.NetworkConfig` it
is `testnet.toml`. Here are examples of these files:
```toml
secret_key = "S..."
```
```toml
horizon_url = "https://horizon-testnet.stellar.org"
rpc_url = "https://soroban-testnet.stellar.org"
network_passphrase = "Test SDF Network ; September 2015"
```
Any of these fields can be set as an environment variable.
## Acknowledgements
This repository has no affiliation with the Stellar Developer Foundation.
The official CLI can be found here https://github.com/stellar/soroban-cli
Should this become useful, I am happy to transfer it as well to the SDF org!
Raw data
{
"_id": null,
"home_page": "",
"name": "soroban",
"maintainer": "Soroban API/CLI contributors",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "blockchain,cryptocurrency,dex,distributed exchange,horizon,lumens,sdex,soroban,soroban-rpc,stellar,stellar-sdk,stellar.org,trading,xlm",
"author": "Pamphile Roy",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/3e/70/6380ebb75667577aedccd0e583ba6e98e35e2c76adcc6f0cf392d6a32474/soroban-0.4.0.tar.gz",
"platform": null,
"description": "# API and CLI for Soroban contracts in Python\n\nThis package provide tools to interact with Soroban contracts in Python. The\ngoal is to provide a simple feature set while not depending on the Rust SDK.\nThis can be useful in environment where Rust and the SDK might be more\ndifficult to get working (like a Raspberry Pi).\n\n## Getting started\n\n```\npip install soroban\n```\n\nThis provides a simple way to call contracts without needing to install the\nRust SDK and is a higher level interface compared to using the Python SDK.\n\n```python\nimport soroban\n\nsoroban.invoke(contract_id=\"AAAA...\", function_name=\"increment\")\n```\n\nIdentity and Network configurations are automatically pulled from the global\nor local configuration.\n\nIt also provides a CLI\n```shell\nsoroban invoke C... version --source-account=...\n```\n\n## Usage\n\nThe main feature is to be able to call a Soroban contract function: `soroban.invoke`.\n\n```python\nimport soroban\n\nsoroban.invoke(contract_id=\"AAAA...\", function_name=\"increment\")\n```\n\nIt also supports passing arguments as a list of `stellar_sdk.SCVal`. This list\ncan be easily generated\n\n```python\nimport json\nimport soroban\n\nargs = json.load(...)\nargs = soroban.Parameters(args=args).model_dump()\nsoroban.invoke(contract_id=\"AAAA...\", function_name=\"init\", args=args)\n```\n\nThe following JSON syntax is supported. Note that vectors are also supported:\n```json\n[\n {\n \"name\": \"issuer\",\n \"type\": \"address\",\n \"value\": \"C...\"\n },\n {\n \"name\": \"distributor\",\n \"type\": \"int128\",\n \"value\": 10\n },\n {\n \"name\": \"claimants\",\n \"type\": \"vec\",\n \"value\": [\n {\n \"type\": \"uint32\",\n \"value\": 12\n },\n {\n \"type\": \"int64\",\n \"value\": 20\n }\n ]\n }\n]\n```\n\nA few helper functions are also provided:\n\n- `soroban.create_account`: create and fund an account from a source account;\n- `soroban.create_asset`: create an asset using the classical issuer/distributor model.\n\n## Configuration\n\nThe source account and the network to use are set by instantiating `soroban.Identity`\nand `soroban.NetworkConfig`, respectively:\n\n```python\nimport soroban\n\nidentity = soroban.Identity()\nnetwork = soroban.NetworkConfig()\n```\n\nIn both cases, the configuration can be set by either adjusting init arguments,\nsetting up environment variables or using configuration files in toml.\n\nThe default path for `soroban.Identity` is `identity.toml` and for `soroban.NetworkConfig` it\nis `testnet.toml`. Here are examples of these files:\n\n```toml\nsecret_key = \"S...\"\n```\n\n```toml\nhorizon_url = \"https://horizon-testnet.stellar.org\"\nrpc_url = \"https://soroban-testnet.stellar.org\"\nnetwork_passphrase = \"Test SDF Network ; September 2015\"\n```\n\nAny of these fields can be set as an environment variable.\n\n## Acknowledgements\n\nThis repository has no affiliation with the Stellar Developer Foundation.\nThe official CLI can be found here https://github.com/stellar/soroban-cli\nShould this become useful, I am happy to transfer it as well to the SDF org!\n",
"bugtrack_url": null,
"license": "",
"summary": "API and CLI for Soroban contracts in Python",
"version": "0.4.0",
"project_urls": {
"documentation": "https://github.com/tupui/soroban-cli-python",
"homepage": "https://github.com/tupui/soroban-cli-python",
"source": "https://github.com/tupui/soroban-cli-python"
},
"split_keywords": [
"blockchain",
"cryptocurrency",
"dex",
"distributed exchange",
"horizon",
"lumens",
"sdex",
"soroban",
"soroban-rpc",
"stellar",
"stellar-sdk",
"stellar.org",
"trading",
"xlm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d27171e39d430abe12de74423e64665eea8e1cbea9d4c827ef929f6084ce1b3",
"md5": "5ff0ed69ab122dcb9070d95b54d48b29",
"sha256": "2dfdfa53126a24e888027403ff727df37ba66e837b316efa442fc1c1bc9a42a6"
},
"downloads": -1,
"filename": "soroban-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ff0ed69ab122dcb9070d95b54d48b29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8529,
"upload_time": "2024-03-12T02:10:12",
"upload_time_iso_8601": "2024-03-12T02:10:12.507149Z",
"url": "https://files.pythonhosted.org/packages/0d/27/171e39d430abe12de74423e64665eea8e1cbea9d4c827ef929f6084ce1b3/soroban-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e706380ebb75667577aedccd0e583ba6e98e35e2c76adcc6f0cf392d6a32474",
"md5": "6a7faf98b9eb2c7557ffdadc384b34d6",
"sha256": "6aa136f10b224921237eb302c915b47783989b256132ebda8d0e1b74eb72a8fe"
},
"downloads": -1,
"filename": "soroban-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6a7faf98b9eb2c7557ffdadc384b34d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9360,
"upload_time": "2024-03-12T02:10:17",
"upload_time_iso_8601": "2024-03-12T02:10:17.097080Z",
"url": "https://files.pythonhosted.org/packages/3e/70/6380ebb75667577aedccd0e583ba6e98e35e2c76adcc6f0cf392d6a32474/soroban-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-12 02:10:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tupui",
"github_project": "soroban-cli-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "soroban"
}
JSON
