Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bridge-sdk/pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "aleo-bridge-sdk"
version = "0.8.0"
version = "0.9.0"
description = "Bridge Aleo, Ethereum, BSC, Arc, Base, Arbitrum and Solana assets with Hyperlane, Verulink, Circle xReserve and CCTP"
readme = "README.md"
requires-python = ">=3.10"
Expand Down
2 changes: 1 addition & 1 deletion bridge-sdk/python/aleo_bridge/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

from pathlib import Path

__version__ = "0.8.0"
__version__ = "0.9.0"
_ALEO_SDK_MINIMUM = "0.7.0"


Expand Down
2 changes: 1 addition & 1 deletion bridge-sdk/tests/test_client_lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ def test_public_exports_pin_pre_existing_set_and_add_lifecycle_names():
assert hasattr(aleo_bridge, name), name
assert set(PRE_EXISTING_EXPORTS) <= set(aleo_bridge.__all__)
assert set(NEW_EXPORTS) <= set(aleo_bridge.__all__)
assert aleo_bridge.__version__ == "0.8.0"
assert aleo_bridge.__version__ == "0.9.0"
assert aleo_bridge.lifecycle is lifecycle
assert aleo_bridge.prepare is lifecycle.prepare
assert aleo_bridge.bridge_tools is agent.bridge_tools
Expand Down
4 changes: 2 additions & 2 deletions bridge-sdk/tests/test_package.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

def test_version_is_pinned_in_lockstep():
pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
assert pyproject["project"]["version"] == "0.8.0" == aleo_bridge.__version__
assert pyproject["project"]["version"] == "0.9.0" == aleo_bridge.__version__
assert pyproject["project"]["name"] == "aleo-bridge-sdk"
deps = pyproject["project"]["dependencies"]
for base in ("aleo-sdk", "pynacl", "web3", "eth-account", "solders", "solana", "privy-client", "dynamic-wallet-sdk"):
Expand Down Expand Up @@ -105,7 +105,7 @@ def test_import_without_optional_extras(monkeypatch):
monkeypatch.delitem(sys.modules, name) # reverted at teardown — a fresh reimport below must not
# leak new module/class objects into tests that run after this one
pkg = importlib.import_module("aleo_bridge")
assert pkg.__version__ == "0.8.0"
assert pkg.__version__ == "0.9.0"
assert issubclass(pkg.RouteNotFoundError, pkg.BridgeError)


Expand Down
2 changes: 1 addition & 1 deletion sdk-abi/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion sdk-abi/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

[package]
name = "aleo-abi"
version = "0.8.0"
version = "0.9.0"
edition = "2024"
license = "GPL-3.0-or-later"
description = "Python bindings for ABI generation from Aleo bytecode (via Leo's leo-abi crate)"
Expand Down
2 changes: 1 addition & 1 deletion sdk-abi/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "maturin"

[project]
name = "aleo-contract-abi-generator"
version = "0.8.0"
version = "0.9.0"
description = "Python bindings for ABI generation from Aleo bytecode"
readme = "README.md"
license = {text = "GPL-3.0-or-later"}
Expand Down
2 changes: 1 addition & 1 deletion sdk/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion sdk/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "aleo"
authors = ["Konstantin Pandl", "Mike Turner", "Roman Proskuryakov"]
version = "0.8.0"
version = "0.9.0"
description = "A Python sdk for zero-knowledge cryptography based on Aleo"
edition = "2021"
license = "GPL-3.0-or-later"
Expand Down
2 changes: 1 addition & 1 deletion sdk/docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
copyright = '2019-2026, Provable Inc.'
author = 'kpp'

version = '0.8.0'
version = '0.9.0'

# -- General configuration

Expand Down
2 changes: 1 addition & 1 deletion sdk/pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[project]
name = "aleo-sdk"
description = "Python SDK for building zero-knowledge apps and DeFi on the Aleo network"
version = "0.8.0"
version = "0.9.0"
readme = "Readme.md"
license = {file = "LICENSE.md"}
authors = [
Expand Down
86 changes: 62 additions & 24 deletions shield-swap-sdk/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,13 @@ Typed Python client for the shield_swap AMM on Aleo
MCP alternative: `python -m aleo_shield_swap.mcp` exposes the same
lifecycle as tools.

## Tier 1 — the lifecycle (six lines end to end)
## Tier 1 — start and resume a trading session

```python
from aleo_shield_swap import ShieldSwap
from aleo_shield_swap import Profile, ShieldSwap

dex = ShieldSwap.from_profile() # key material auto-managed on disk
Profile.load_or_create(storage="encrypted") # Protect a new key; existing storage stays unchanged.
dex = ShieldSwap.from_profile() # Resume with the same account and journal.
dex.onboard() # first run registers; no-op afterwards
pools = dex.api.get_pools()
report = dex.swap_many(pool_key=pools[0].key, token_in_id=pools[0].token0,
Expand All @@ -23,23 +24,54 @@ dex.collect_all() # any session, any time

### `from_profile(home: 'Any' = None, *, network: 'Optional[str]' = None, endpoint: 'Optional[str]' = None) -> "'ShieldSwap'"`

The client for the local participant profile (created on first use).
Continue trading with the same account, credentials, and swap journal.

Wires endpoint, network, signer, and (when present) delegated-proving
credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run
``onboard()`` next on a fresh profile.
Use the same *home* on each run to retain pending swaps and saved API
credentials. On first use, the client uses an existing Aleo account
or creates one. To keep an existing address and its funds, import
that account before starting; see :meth:`Profile.load_or_create`.

*network* and *endpoint* apply only when the profile is being created —
an existing one keeps what it was created with, because its derived pool
keys and blinded identities are network-scoped and would not transfer.
Give each network its own home directory.
For a new account, use macOS Keychain or password encryption to
protect the private key. Set this up before building the client::

from aleo_shield_swap import Profile, ShieldSwap

Profile.load_or_create(storage="encrypted")
dex = ShieldSwap.from_profile()

This prompts for a password if none is supplied by the environment
or Keychain. It does not change an account's existing storage.
Without this setup, a generated key is saved as plaintext: anyone
who can read the account file can spend its funds. Use
``storage="keychain"`` on macOS to keep the key outside the file.

An encrypted account needs its password each time the client starts.
For unattended runs, set ``ALEO_ACCOUNT_PASSWORD`` or save the password
in the macOS Keychain. A key supplied through ``ALEO_PRIVATE_KEY`` or
``ALEO_PRIVATE_KEY_FILE`` must also be supplied each run; it is never
saved by the profile.

The client attempts to register with the hosted record scanner,
sharing the account's view key so the scanner can read its records.
For a custom record provider, construct ``ShieldSwap(aleo)`` instead.
Call ``onboard()`` to register a new account with Shield Swap before
trading. Client construction does not submit a trade.

Args:
home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or
``~/.shield-swap``.
network: ``"mainnet"`` or ``"testnet"`` for a NEW profile; defaults
to testnet.
endpoint: Node API origin for a NEW profile.
home: Directory holding the profile and its saved work. Defaults to
``SHIELD_SWAP_HOME``, then ``~/.shield-swap``. Use a separate
directory for each network.
network: ``"mainnet"`` or ``"testnet"``; defaults to testnet for a
new profile. An existing profile keeps its recorded network.
endpoint: API service root for a new profile; defaults to
``https://edge.provable.com/api``. Ignored for an existing profile.

Raises:
aleo.keystore.KeystoreError: The account cannot be opened. Check
``code``: ``PASSWORD_REQUIRED`` means a password must be supplied;
``ACCOUNT_NOT_FOUND`` means an existing profile's key is missing;
``ADDRESS_MISMATCH`` means the selected key belongs to another
address. Restore the intended key before trying again.

### `onboard(self, referral_code: 'Optional[str]' = None) -> 'OnboardReport'`

Expand Down Expand Up @@ -99,13 +131,19 @@ reports. Requires ``from_profile()``.

### Before doing anything: two questions

1. **Existing account?** When `status()` shows a brand-new, unregistered
profile, ask whether the user already has a shield-swap account before
creating anything — their funds and access live on the old key.
**NEVER ask the user to paste a private key into the conversation.**
They supply it out-of-band: `export SHIELD_SWAP_PRIVATE_KEY=...` (or
`SHIELD_SWAP_PRIVATE_KEY_FILE=path`) in their own shell before the
profile is first created.
1. **Existing account?** Ask before creating a profile: an existing
account's funds stay with its original key. Have the user import that key
in their own terminal with
`python -m aleo.keystore import --storage encrypted`, or use
`--storage keychain` on macOS. These protect the saved key; plaintext
storage leaves it readable to anyone with access to the account file.
After import, `Profile.load_or_create(create=False)` requires that account
rather than generating another key if setup is missing.
**Never ask for a private key in the conversation.** Do not run
`python -m aleo.keystore export` or read account files to inspect an
address; use `python -m aleo.keystore show` instead. An account supplied
through `ALEO_PRIVATE_KEY` or `ALEO_PRIVATE_KEY_FILE` must be supplied
each run; the profile does not save that key.
2. **Referral code — optional.** Access is granted by authentication
alone; `onboard()` needs nothing from the user. Mention that a
referral code from a friend can be passed (`onboard(referral_code=)`)
Expand Down Expand Up @@ -184,7 +222,7 @@ where the signing keys live:

| Building | Stack | Keys live |
| --- | --- | --- |
| Bot / server / CLI / notebook | `aleo-sdk` facade + `shield-swap-sdk` (this package) | A local private key (`ShieldSwap.from_profile()` manages it); delegated proving through the Provable prover — fees covered by default. |
| Bot / server / CLI / notebook | `aleo-sdk` facade + `shield-swap-sdk` (this package) | A saved Aleo account. Import an existing key to retain its funds, or create an account with Keychain or encrypted storage before calling `ShieldSwap.from_profile()`. Delegated proving uses the Provable prover; fees are covered by default. |
| Agent integration | `aleo_shield_swap.agent` (Claude-shape tool schemas + `dispatch_tool`) or `python -m aleo_shield_swap.mcp` (MCP server), over the same client | Same as the underlying client; the tools bind to it. |
| Browser dApp (wallet-signed) | The TypeScript stack: `@provablehq/shield-swap-sdk` + Veil react hooks — not this package | The user's wallet signs and proves. |

Expand Down
120 changes: 119 additions & 1 deletion shield-swap-sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ pip install -e "shield-swap-sdk[async]" # + AsyncShieldSwap (httpx)
pip install -e "shield-swap-sdk[mcp]" # + the MCP server
```

Requires `aleo-sdk>=0.8.0` (this repo's SDK; imports as `aleo`) and Python 3.10+.
Requires `aleo-sdk>=0.9.0` (this repo's SDK; imports as `aleo`) and Python 3.10+.

## First swap example

Expand Down Expand Up @@ -72,6 +72,124 @@ Claude Code users get it via the `shield-swap` skill (packaged under
`aleo_shield_swap/skills/`, copy into `.claude/skills/`); any MCP client
can run the same lifecycle through `python -m aleo_shield_swap.mcp`.

## Keep using the same account

A profile keeps an account's address, API credentials, and swap journal
together so a script can resume trading or collect unfinished swaps after a
restart. Use the same profile directory on each run: `~/.shield-swap` by
default, or a directory selected with `SHIELD_SWAP_HOME` or the `home` argument.

Profile directories that use one account on one network share its swap
counters through `~/.aleo/shield-swap/counters/<network>/<address>.jsonl`, so
their swaps never reuse a blinded identity. Each directory keeps its own
journal: collect a swap from the profile that made it.

### Use an existing account

Import the account to keep its address and funds. Run this in a terminal;
the command asks for the private key without displaying it:

```sh
python -m aleo.keystore import --name trading --storage encrypted
```

Then create a profile for that account. `create=False` requires an existing
key, so a missing account produces an error instead of a new address.

```python
from aleo_shield_swap import Profile, ShieldSwap

profile = Profile.load_or_create(account="trading", create=False)
dex = ShieldSwap.from_profile(profile.home)
```

On later runs, `ShieldSwap.from_profile()` reuses the saved account, credentials,
and journal. An encrypted account needs its password when the client starts.

### Protect a new account's key

Use macOS Keychain or encrypted storage for saved keys. The default is
plaintext, so choose storage before generating an account:

```python
from aleo_shield_swap import Profile, ShieldSwap

Profile.load_or_create(storage="encrypted")
dex = ShieldSwap.from_profile()
```

The first call asks for an encryption password if none was supplied. On macOS,
use `storage="keychain"` to keep the private key outside the account file.
The choices differ in what access to that file reveals:

| Storage | Where the key is kept | What unlocks it |
| --- | --- | --- |
| `"keychain"` (macOS) | In macOS Keychain; the account file contains a reference to it. | Access to the Keychain entry. Copying the account file does not copy the key. |
| `"encrypted"` | Encrypted inside the account file. | The account password. A copy or backup remains encrypted. |
| `"plaintext"` (default) | Readable inside the account file. | Nothing beyond access to the file. Owner-only permissions do not encrypt the key or protect a copied file. |

Anyone who obtains the private key can spend the account's funds. The address
remains readable in the account file in every mode.

`storage` only applies when generating a key. To protect an account that
already exists, change its storage without changing its address or funds:

```sh
python -m aleo.keystore protect --name trading --storage encrypted
```

To create a separate account, choose both an unused `account` name and a
separate profile directory. A second directory alone reuses the same account.
Clear any private-key variables first, since those take precedence over the
named account.

### Run without a password prompt

For `ShieldSwap.from_profile()` and MCP, set `ALEO_ACCOUNT_PASSWORD` or save
the encryption password in macOS Keychain. When creating an encrypted account,
`save_password=True` saves the password there so later runs can unlock it
without a prompt. The password is still needed; Keychain supplies it.

Code that uses `Profile` directly can also pass `password` to
`Profile.load_or_create`. That password is kept only by the returned object;
it is not passed on to a later `ShieldSwap.from_profile()` call. Without a
password source, unlocking asks at a hidden terminal prompt, which unattended
scripts and MCP servers cannot answer.

A key supplied through `ALEO_PRIVATE_KEY` or `ALEO_PRIVATE_KEY_FILE` is used
before a saved key and is never copied to disk. Supply it on every run, or
import it once to save it. `SHIELD_SWAP_PRIVATE_KEY` and
`SHIELD_SWAP_PRIVATE_KEY_FILE` are also accepted. Any supplied key must match
the profile's address and the selected account file, if one exists.

Account files default to `~/.aleo/accounts/<name>.json`. The name comes from
`account`, then `ALEO_ACCOUNT`, then the profile's saved name, then `default`.
Use `accounts_dir` or `ALEO_ACCOUNTS_DIR` for another directory. The profile
does not save that location, so supply it on each run; clients opened with
`ShieldSwap.from_profile()` need `ALEO_ACCOUNTS_DIR` for a custom location.

Opening an existing `Profile` does not require its key. Reading
`profile.private_key` unlocks it and checks the address. Failures raise
`aleo.keystore.KeystoreError`; check `error.code` for a missing account
(`ACCOUNT_NOT_FOUND`), a needed password (`PASSWORD_REQUIRED`), or a key for
another address (`ADDRESS_MISMATCH`). See
[`aleo.keystore`](../sdk/Readme.md#store-an-account--aleokeystore) for the full
account API.

### Move a key out of an older profile

Older profiles with a private key in `profile.json` still work. Using that key
logs a migration command once per profile file per process. To encrypt the key
and remove the plaintext copy from the profile, run:

```sh
python -m aleo.keystore migrate --from ~/.shield-swap/profile.json --storage encrypted --remove-legacy-key
```

Without `--remove-legacy-key`, migration leaves the plaintext key in
`profile.json`. Existing backups also retain their copies. Earlier SDK releases
cannot read a profile after its key has been removed.

## How calls work

Every read returns a value immediately. Every write returns a prepared
Expand Down
Loading
Loading