diff --git a/README.md b/README.md index 798563c..ab44be1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ -# Soroban CLI +# API and CLI for Soroban contracts in Python -CLI and functions to call Soroban contracts with 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 @@ -12,17 +17,106 @@ Rust SDK and is a higher level interface compared to using the Python SDK. ```python import soroban -soroban.invoke("AAAA...", "increment") +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 -```bash -soroban invoke CC22IAGPHR4DXI73WSI4L65TTB3F5A2DF7FP5PPNIOLVX5NQWSVR4TID version --source-account=... +```shell +soroban invoke C... version --source-account=... ``` -> Note: 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! +## 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! diff --git a/pyproject.toml b/pyproject.toml index bf7f903..80a921d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "soroban" dynamic = ["version"] -description = "CLI for Soroban contracts in Python" +description = "API and CLI for Soroban contracts in Python" readme = "README.md" requires-python = ">=3.11" license = "BSD-3-Clause" @@ -13,7 +13,7 @@ authors = [ { name = "Pamphile Roy" }, ] maintainers = [ - { name = "Soroban CLI contributors" }, + { name = "Soroban API/CLI contributors" }, ] keywords = [ diff --git a/tests/test_create.py b/tests/test_create.py index 8fb3847..5bfc493 100644 --- a/tests/test_create.py +++ b/tests/test_create.py @@ -1,3 +1,5 @@ +from decimal import Decimal + import pytest import soroban @@ -14,4 +16,4 @@ def test_create_account(): def test_create_asset(): source_account = "SDEUQZ7PMHT7VDP3TYZMBKUVES3W6CTXT5L2ZR5NROWQJIDE4QFUXW6Q" - soroban.create_account(name="BOB", source_account=source_account) + soroban.create_asset(name="BOBI", mint=Decimal(10), source_account=source_account)