# 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
local configuration or the current working directory. See bellow.
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)
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": null,
"name": "soroban",
"maintainer": "Soroban API/CLI contributors",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "blockchain, cryptocurrency, dex, distributed exchange, horizon, lumens, sdex, soroban, soroban-rpc, stellar, stellar-sdk, stellar.org, trading, xlm",
"author": "Pamphile Roy",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9e/2d/8c9c3f3f465e4ac647bd66096290bedf0a5631ee762ee3c59662e57439d2/soroban-0.9.1.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\nlocal configuration or the current working directory. See bellow.\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)\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": null,
"summary": "API and CLI for Soroban contracts in Python",
"version": "0.9.1",
"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": "722e5fa9600340773d516c3a88831a1fa414bfbca5404fb524aefbb19bb71144",
"md5": "6add22b70e4e52e5c6818bfcc6df247b",
"sha256": "1a9aa2535603942486bbadf19aca95816af400221cc808575c68cb48b4c2e621"
},
"downloads": -1,
"filename": "soroban-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6add22b70e4e52e5c6818bfcc6df247b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9315,
"upload_time": "2024-11-12T01:04:25",
"upload_time_iso_8601": "2024-11-12T01:04:25.425887Z",
"url": "https://files.pythonhosted.org/packages/72/2e/5fa9600340773d516c3a88831a1fa414bfbca5404fb524aefbb19bb71144/soroban-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9e2d8c9c3f3f465e4ac647bd66096290bedf0a5631ee762ee3c59662e57439d2",
"md5": "826de88e98e68b2ec6c89e7e31f871b6",
"sha256": "b5c7c3b73ac0706967f2b9bd17e7e05c6c28dd285dcca0ebee57a4a36d41e7a1"
},
"downloads": -1,
"filename": "soroban-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "826de88e98e68b2ec6c89e7e31f871b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9869,
"upload_time": "2024-11-12T01:04:26",
"upload_time_iso_8601": "2024-11-12T01:04:26.647533Z",
"url": "https://files.pythonhosted.org/packages/9e/2d/8c9c3f3f465e4ac647bd66096290bedf0a5631ee762ee3c59662e57439d2/soroban-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 01:04:26",
"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
