Metadata-Version: 2.3
Name: soroban
Version: 0.6.0
Summary: API and CLI for Soroban contracts in Python
Project-URL: homepage, https://github.com/tupui/soroban-cli-python
Project-URL: documentation, https://github.com/tupui/soroban-cli-python
Project-URL: source, https://github.com/tupui/soroban-cli-python
Author: Pamphile Roy
Maintainer: Soroban API/CLI contributors
License-Expression: BSD-3-Clause
License-File: LICENSE.txt
Keywords: blockchain,cryptocurrency,dex,distributed exchange,horizon,lumens,sdex,soroban,soroban-rpc,stellar,stellar-sdk,stellar.org,trading,xlm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: stellar-sdk
Requires-Dist: tomli-w
Provides-Extra: cli
Requires-Dist: typer[all]; extra == 'cli'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: typer[all]; extra == 'dev'
Provides-Extra: tests
Requires-Dist: pytest; extra == 'tests'
Requires-Dist: pytest-cov; extra == 'tests'
Description-Content-Type: text/markdown

# 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!
