Update Readme

Author: tupui

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!

pyproject.toml

@@ -5,15 +5,15 @@ 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"
 authors = [
     { name = "Pamphile Roy" },
 ]
 maintainers = [
-    { name = "Soroban CLI contributors" },
+    { name = "Soroban API/CLI contributors" },
 ]
 
 keywords = [

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)