From b7cc024d5200ccc92f9921309d2bc2da19e86f60 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 08:48:17 -0500 Subject: [PATCH 1/9] feat(shield-swap): keep the profile account in the account keystore Profile.load_or_create() stored its private key in profile.json. It now finds and stores the key through aleo.keystore, so one account file serves the Python SDK, Veil scripts and the Shield Swap command line. - A new home looks the account up first (the key variables, then the account file) and creates and stores one only when none is found and create is true. - load_or_create() gains create, storage, account, accounts_dir, password and save_password. - A new profile.json records the address and the account name and holds no key. An existing profile.json with a key keeps working and logs one line pointing at python -m aleo.keystore migrate. - A key from the environment is used for the process and is no longer copied to disk. All packages move to 0.9.0, and aleo-shield-swap now requires aleo-sdk>=0.9.0, the first release with aleo.keystore. --- bridge-sdk/pyproject.toml | 2 +- bridge-sdk/python/aleo_bridge/__init__.py | 2 +- bridge-sdk/tests/test_client_lifecycle.py | 2 +- bridge-sdk/tests/test_package.py | 4 +- sdk-abi/Cargo.lock | 2 +- sdk-abi/Cargo.toml | 2 +- sdk-abi/pyproject.toml | 2 +- sdk/Cargo.lock | 2 +- sdk/Cargo.toml | 2 +- sdk/docs/source/conf.py | 2 +- sdk/pyproject.toml | 2 +- shield-swap-sdk/AGENTS.md | 30 +- shield-swap-sdk/README.md | 73 +- shield-swap-sdk/codegen/gen_context.py | 14 +- shield-swap-sdk/examples/first-swap/README.md | 7 +- shield-swap-sdk/examples/first-swap/swap.py | 3 +- shield-swap-sdk/pyproject.toml | 4 +- .../python/aleo_shield_swap/AGENTS.md | 30 +- .../python/aleo_shield_swap/__init__.py | 15 +- .../python/aleo_shield_swap/client.py | 16 + .../python/aleo_shield_swap/mcp.py | 12 +- .../python/aleo_shield_swap/profile.py | 271 +++++-- shield-swap-sdk/tests/conftest.py | 100 ++- .../integration/test_agent_lifecycle_live.py | 2 +- .../tests/integration/test_swap_lifecycle.py | 2 +- .../tests/test_first_swap_account.py | 22 +- shield-swap-sdk/tests/test_gen_context.py | 5 +- shield-swap-sdk/tests/test_package.py | 8 +- shield-swap-sdk/tests/test_profile.py | 738 +++++++++++++++++- 29 files changed, 1227 insertions(+), 149 deletions(-) diff --git a/bridge-sdk/pyproject.toml b/bridge-sdk/pyproject.toml index f16bd112..ea031be6 100644 --- a/bridge-sdk/pyproject.toml +++ b/bridge-sdk/pyproject.toml @@ -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" diff --git a/bridge-sdk/python/aleo_bridge/__init__.py b/bridge-sdk/python/aleo_bridge/__init__.py index 42119445..2a29a117 100644 --- a/bridge-sdk/python/aleo_bridge/__init__.py +++ b/bridge-sdk/python/aleo_bridge/__init__.py @@ -8,7 +8,7 @@ from pathlib import Path -__version__ = "0.8.0" +__version__ = "0.9.0" _ALEO_SDK_MINIMUM = "0.7.0" diff --git a/bridge-sdk/tests/test_client_lifecycle.py b/bridge-sdk/tests/test_client_lifecycle.py index ade27af2..02f1e8e5 100644 --- a/bridge-sdk/tests/test_client_lifecycle.py +++ b/bridge-sdk/tests/test_client_lifecycle.py @@ -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 diff --git a/bridge-sdk/tests/test_package.py b/bridge-sdk/tests/test_package.py index 32a65527..5d0b6fa8 100644 --- a/bridge-sdk/tests/test_package.py +++ b/bridge-sdk/tests/test_package.py @@ -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"): @@ -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) diff --git a/sdk-abi/Cargo.lock b/sdk-abi/Cargo.lock index cc2cf527..112ff1e8 100644 --- a/sdk-abi/Cargo.lock +++ b/sdk-abi/Cargo.lock @@ -19,7 +19,7 @@ checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" [[package]] name = "aleo-abi" -version = "0.8.0" +version = "0.9.0" dependencies = [ "anyhow", "leo-abi", diff --git a/sdk-abi/Cargo.toml b/sdk-abi/Cargo.toml index 7bd35f7f..15dd9eef 100644 --- a/sdk-abi/Cargo.toml +++ b/sdk-abi/Cargo.toml @@ -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)" diff --git a/sdk-abi/pyproject.toml b/sdk-abi/pyproject.toml index b64c6045..e243904d 100644 --- a/sdk-abi/pyproject.toml +++ b/sdk-abi/pyproject.toml @@ -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"} diff --git a/sdk/Cargo.lock b/sdk/Cargo.lock index 28ea9d1d..96fdf937 100644 --- a/sdk/Cargo.lock +++ b/sdk/Cargo.lock @@ -37,7 +37,7 @@ dependencies = [ [[package]] name = "aleo" -version = "0.8.0" +version = "0.9.0" dependencies = [ "anyhow", "hex", diff --git a/sdk/Cargo.toml b/sdk/Cargo.toml index f8a34c65..d712c502 100644 --- a/sdk/Cargo.toml +++ b/sdk/Cargo.toml @@ -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" diff --git a/sdk/docs/source/conf.py b/sdk/docs/source/conf.py index 04468ca7..98f26ae7 100644 --- a/sdk/docs/source/conf.py +++ b/sdk/docs/source/conf.py @@ -11,7 +11,7 @@ copyright = '2019-2026, Provable Inc.' author = 'kpp' -version = '0.8.0' +version = '0.9.0' # -- General configuration diff --git a/sdk/pyproject.toml b/sdk/pyproject.toml index 33c1f338..53006484 100644 --- a/sdk/pyproject.toml +++ b/sdk/pyproject.toml @@ -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 = [ diff --git a/shield-swap-sdk/AGENTS.md b/shield-swap-sdk/AGENTS.md index 3d43c60e..7a119be4 100644 --- a/shield-swap-sdk/AGENTS.md +++ b/shield-swap-sdk/AGENTS.md @@ -13,7 +13,7 @@ lifecycle as tools. ```python from aleo_shield_swap import ShieldSwap -dex = ShieldSwap.from_profile() # key material auto-managed on disk +dex = ShieldSwap.from_profile() # account from the Aleo keystore, created on first use 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, @@ -29,11 +29,27 @@ Wires endpoint, network, signer, and (when present) delegated-proving credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run ``onboard()`` next on a fresh profile. +The signer is the profile's Aleo account, found through the account +keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or +``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in +``~/.aleo/accounts`` that the profile names. A fresh profile adopts +that account, or creates one and stores it there; the profile itself +holds no private key, and a key from the environment is never written +to disk. To create the account encrypted, in the macOS Keychain or +under another name, call :meth:`Profile.load_or_create` on the same +*home* first. + *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. +Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key +cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address +than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account +with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an +existing profile is no longer supplied. + Args: home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``. @@ -103,9 +119,13 @@ reports. Requires ``from_profile()``. 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. + They supply it out-of-band, in their own terminal, before the profile is + first created: `python -m aleo.keystore import` stores it once (hidden + prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or + `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from + the environment is never written to disk. The key lives in the Aleo + account keystore (`~/.aleo/accounts/`), not in the profile; never run + `python -m aleo.keystore export` or read an account file, both reveal it. 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=)`) @@ -184,7 +204,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 local private key in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); delegated proving through the Provable prover — fees 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. | diff --git a/shield-swap-sdk/README.md b/shield-swap-sdk/README.md index 57ab64f7..663e8f34 100644 --- a/shield-swap-sdk/README.md +++ b/shield-swap-sdk/README.md @@ -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 @@ -72,6 +72,77 @@ 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`. +## Profiles and the account key + +`ShieldSwap.from_profile()` and `Profile.load_or_create()` keep a trader's +state between runs in a profile home (`~/.shield-swap`, `SHIELD_SWAP_HOME`, +or the `home` argument): API credentials, the swap journal, and +`profile.json`, which records the account's address, its account name, the +network and the endpoint. + +The private key is not in the profile. It is found through the Aleo SDK's +account keystore ([`aleo.keystore`](../sdk/Readme.md#store-an-account--aleokeystore)), +which the other Aleo tools read as well, so an account set up once serves all +of them: + +1. `ALEO_PRIVATE_KEY`, or the text file named by `ALEO_PRIVATE_KEY_FILE` + (`SHIELD_SWAP_PRIVATE_KEY` and `SHIELD_SWAP_PRIVATE_KEY_FILE` are aliases). + A key supplied this way is used for the process and never written to disk, + so it has to be supplied on every run. +2. The account file `~/.aleo/accounts/.json`. The name comes from the + `account` argument, then `ALEO_ACCOUNT`, then the name recorded in the + profile, then `default`. + +A new profile adopts the account those sources supply. When there is none it +creates an account and stores it in the keystore; `create=False` raises +instead. Two profile homes that select the same account name therefore share +one account: give a second address its own home and its own `account` name. +Whichever source supplies the key later, it must belong to the +address the profile records, so a stale variable or the wrong account name is +an error naming both addresses instead of a trade from another account. + +```python +from aleo_shield_swap import Profile, ShieldSwap + +# First run: adopt the stored account, or create one and store it. +profile = Profile.load_or_create() + +# Or choose how a newly created key is held, then build the client. An +# encrypted account takes its password from ALEO_ACCOUNT_PASSWORD or asks for +# it twice on the terminal. +Profile.load_or_create("~/.shield-swap-main", network="mainnet", account="mainnet", + storage="encrypted", save_password=True) +dex = ShieldSwap.from_profile("~/.shield-swap-main") +``` + +`storage` applies when an account is created: `"plaintext"` (the default) is +a file only its owner can read; `"keychain"` keeps the key in the macOS login +keychain; `"encrypted"` encrypts it under a password, which later runs take +from the `password` argument, `ALEO_ACCOUNT_PASSWORD`, the macOS Keychain +(`save_password=True`, macOS only) or a hidden prompt on a terminal. Keychain and +encrypted storage protect a copied or backed-up file; they do not stop +another process running as the same user. An unattended job with an encrypted +account needs the variable or the saved password, because it cannot answer a +prompt. + +`profile.private_key` looks the key up on first use and raises +`aleo.keystore.KeystoreError` when it cannot: read `error.code` +(`PASSWORD_REQUIRED`, `ADDRESS_MISMATCH`, `ACCOUNT_NOT_FOUND`, …). +`accounts_dir` (or `ALEO_ACCOUNTS_DIR`) points at another accounts directory; +the profile does not record it, so pass it on every run. + +A profile written by an earlier release keeps its key in `profile.json` and +works unchanged. The first read of its key logs one warning on the +`aleo_shield_swap.profile` logger with the command that moves the key: + +```sh +python -m aleo.keystore migrate --from ~/.shield-swap/profile.json --remove-legacy-key +``` + +Without `--remove-legacy-key` the command copies the key and leaves the +plaintext copy in `profile.json`. Earlier releases cannot read a profile that +no longer holds the key. + ## How calls work Every read returns a value immediately. Every write returns a prepared diff --git a/shield-swap-sdk/codegen/gen_context.py b/shield-swap-sdk/codegen/gen_context.py index 9c684b1b..e9ee0da5 100644 --- a/shield-swap-sdk/codegen/gen_context.py +++ b/shield-swap-sdk/codegen/gen_context.py @@ -45,7 +45,7 @@ ```python from aleo_shield_swap import ShieldSwap -dex = ShieldSwap.from_profile() # key material auto-managed on disk +dex = ShieldSwap.from_profile() # account from the Aleo keystore, created on first use 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, @@ -62,9 +62,13 @@ 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. + They supply it out-of-band, in their own terminal, before the profile is + first created: `python -m aleo.keystore import` stores it once (hidden + prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or + `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from + the environment is never written to disk. The key lives in the Aleo + account keystore (`~/.aleo/accounts/`), not in the profile; never run + `python -m aleo.keystore export` or read an account file, both reveal it. 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=)`) @@ -143,7 +147,7 @@ | 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 local private key in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); delegated proving through the Provable prover — fees 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. | diff --git a/shield-swap-sdk/examples/first-swap/README.md b/shield-swap-sdk/examples/first-swap/README.md index b7db6eed..360a9eb0 100644 --- a/shield-swap-sdk/examples/first-swap/README.md +++ b/shield-swap-sdk/examples/first-swap/README.md @@ -21,8 +21,11 @@ python -m aleo_shield_swap.examples.first_swap.swap ## 1. Create an account -Start with an existing testnet private key or let the SDK create and retain one -in `~/.shield-swap/profile.json`. +Start with an existing testnet private key or let the SDK create and retain +one. `Profile.load_or_create` stores a new account in the Aleo account +keystore (`~/.aleo/accounts/default.json`), where the other Aleo tools find it +too, and records its address in `~/.shield-swap/profile.json`. Later runs +reuse that account. ```python import os diff --git a/shield-swap-sdk/examples/first-swap/swap.py b/shield-swap-sdk/examples/first-swap/swap.py index 5f871308..2577abb9 100644 --- a/shield-swap-sdk/examples/first-swap/swap.py +++ b/shield-swap-sdk/examples/first-swap/swap.py @@ -17,7 +17,8 @@ # Use a configured private key or create a new key. key = os.environ.get("SHIELD_SWAP_PRIVATE_KEY") if not key: - # Load a saved private key from an existing Profile or create a new one. + # Load the profile's account from the Aleo account keystore, or create + # an account and store it there on the first run. profile = Profile.load_or_create(network="testnet") if profile.network != "testnet": raise RuntimeError("This example requires a testnet profile") diff --git a/shield-swap-sdk/pyproject.toml b/shield-swap-sdk/pyproject.toml index fa435f3e..e0c24ee9 100644 --- a/shield-swap-sdk/pyproject.toml +++ b/shield-swap-sdk/pyproject.toml @@ -1,10 +1,10 @@ [project] name = "shield-swap-sdk" -version = "0.8.0" +version = "0.9.0" description = "Python SDK for the shield swap AMM Dex on Aleo" readme = "README.md" requires-python = ">=3.10" -dependencies = ["aleo-sdk>=0.8.0", "requests>=2"] # 0.8.0: aleo.inventory (record management) +dependencies = ["aleo-sdk>=0.9.0", "requests>=2"] # 0.9.0: aleo.keystore (account keystore) [project.optional-dependencies] async = ["httpx>=0.27"] diff --git a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md index 3d43c60e..7a119be4 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md +++ b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md @@ -13,7 +13,7 @@ lifecycle as tools. ```python from aleo_shield_swap import ShieldSwap -dex = ShieldSwap.from_profile() # key material auto-managed on disk +dex = ShieldSwap.from_profile() # account from the Aleo keystore, created on first use 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, @@ -29,11 +29,27 @@ Wires endpoint, network, signer, and (when present) delegated-proving credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run ``onboard()`` next on a fresh profile. +The signer is the profile's Aleo account, found through the account +keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or +``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in +``~/.aleo/accounts`` that the profile names. A fresh profile adopts +that account, or creates one and stores it there; the profile itself +holds no private key, and a key from the environment is never written +to disk. To create the account encrypted, in the macOS Keychain or +under another name, call :meth:`Profile.load_or_create` on the same +*home* first. + *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. +Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key +cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address +than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account +with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an +existing profile is no longer supplied. + Args: home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``. @@ -103,9 +119,13 @@ reports. Requires ``from_profile()``. 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. + They supply it out-of-band, in their own terminal, before the profile is + first created: `python -m aleo.keystore import` stores it once (hidden + prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or + `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from + the environment is never written to disk. The key lives in the Aleo + account keystore (`~/.aleo/accounts/`), not in the profile; never run + `python -m aleo.keystore export` or read an account file, both reveal it. 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=)`) @@ -184,7 +204,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 local private key in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); delegated proving through the Provable prover — fees 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. | diff --git a/shield-swap-sdk/python/aleo_shield_swap/__init__.py b/shield-swap-sdk/python/aleo_shield_swap/__init__.py index 66d8871a..bd2cbb43 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/__init__.py +++ b/shield-swap-sdk/python/aleo_shield_swap/__init__.py @@ -14,18 +14,19 @@ amount_in=10**9).delegate() out = dex.claim_swap_output(handle).delegate() """ -_ALEO_SDK_MINIMUM = "0.8.0" +_ALEO_SDK_MINIMUM = "0.9.0" def _require_aleo_sdk() -> None: - """Fail at import, naming the fix, when the installed aleo-sdk predates ``aleo.inventory``. + """Fail at import, naming the fix, when the installed aleo-sdk predates ``aleo.keystore``. - Record management comes from ``aleo.inventory``, which first shipped in aleo-sdk 0.8.0 - (freeze-list proofs, from ``aleo.compliance``, arrived in 0.7.0). An older install would - otherwise fail on the first import of the client with a bare ``ModuleNotFoundError``. + The account keystore comes from ``aleo.keystore``, which first shipped in aleo-sdk 0.9.0 + (record management, from ``aleo.inventory``, arrived in 0.8.0, and freeze-list proofs, + from ``aleo.compliance``, in 0.7.0). An older install would otherwise fail the first time + a profile looks for its account, with a bare ``ModuleNotFoundError``. """ try: - import aleo.inventory # noqa: F401 + import aleo.keystore # noqa: F401 except ImportError as exc: from importlib.metadata import PackageNotFoundError, version try: @@ -118,7 +119,7 @@ def agent_guide() -> str: return files(__name__).joinpath("AGENTS.md").read_text() -__version__ = "0.8.0" +__version__ = "0.9.0" __all__ = [ "ShieldSwap", "AsyncShieldSwap", "ApiClient", "AsyncApiClient", diff --git a/shield-swap-sdk/python/aleo_shield_swap/client.py b/shield-swap-sdk/python/aleo_shield_swap/client.py index 09acbd15..33f092de 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/client.py +++ b/shield-swap-sdk/python/aleo_shield_swap/client.py @@ -170,11 +170,27 @@ def from_profile(cls, home: Any = None, *, credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run ``onboard()`` next on a fresh profile. + The signer is the profile's Aleo account, found through the account + keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or + ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in + ``~/.aleo/accounts`` that the profile names. A fresh profile adopts + that account, or creates one and stores it there; the profile itself + holds no private key, and a key from the environment is never written + to disk. To create the account encrypted, in the macOS Keychain or + under another name, call :meth:`Profile.load_or_create` on the same + *home* first. + *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. + Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key + cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address + than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account + with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an + existing profile is no longer supplied. + Args: home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``. diff --git a/shield-swap-sdk/python/aleo_shield_swap/mcp.py b/shield-swap-sdk/python/aleo_shield_swap/mcp.py index 6d395060..24a4fc60 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/mcp.py +++ b/shield-swap-sdk/python/aleo_shield_swap/mcp.py @@ -14,8 +14,10 @@ the provider derives ``/v2`` reads, ``/prove``, and ``/scanner`` from it) ALEO_PRIVATE_KEY Explicit signer (overrides the profile); without it - the server binds ShieldSwap.from_profile() — - ~/.shield-swap key material, journal, credentials + the server binds ShieldSwap.from_profile() — the + ~/.shield-swap journal and credentials, signing with + the profile's account from the Aleo account keystore + (~/.aleo/accounts) ALEO_NETWORK ``testnet`` (default) or ``mainnet`` ALEO_E2E_API_KEY / ALEO_E2E_CONSUMER_ID Delegated-proving + hosted-scanner credentials @@ -86,6 +88,7 @@ def _build_dex() -> Any: return ShieldSwap(aleo) # No explicit key: bind the local participant profile (created on first # use), so MCP agents get persistence — journal, counters, credentials. + # Its account comes from the Aleo account keystore. return ShieldSwap.from_profile() @@ -93,7 +96,10 @@ def main() -> None: """Serve the shield_swap MCP tools over stdio until the client disconnects. Builds a DEX client first, which binds a key from ``ALEO_PRIVATE_KEY`` or - else creates/loads the local participant profile on disk. Blocks for the + else creates/loads the local participant profile on disk and signs with + its account from the Aleo account keystore. An encrypted account needs + ``ALEO_ACCOUNT_PASSWORD`` or a password saved in the macOS Keychain here, + because a server on stdio has no terminal to ask on. Blocks for the lifetime of the server; requires the ``[mcp]`` extra. """ import anyio diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index 94bd27b9..5fbb24c5 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -1,21 +1,33 @@ -"""On-disk participant profile — key material, credentials, journal location. +"""On-disk participant profile: account, credentials and journal location. One profile per home directory (``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``). -``Profile.load_or_create()`` generates key material on first use and reuses -it forever after; credentials (JWT, delegated-proving keys) are stored -separately so they can be refreshed without touching the key. +``profile.json`` records which Aleo account the profile trades with: its +address and the name of its account file. The private key itself lives in the +Aleo account keystore (``aleo.keystore``, by default +``~/.aleo/accounts/.json``), which every Aleo tool reads, so an account +set up once serves them all. Credentials (JWT, delegated-proving keys) are +stored separately so they can be refreshed without touching the account. """ from __future__ import annotations import json +import logging import os +import threading from pathlib import Path -from typing import Any, Optional +from typing import Any, Optional, cast DEFAULT_ENDPOINT = "https://edge.provable.com/api" _PROFILE = "profile.json" _CREDENTIALS = "credentials.json" +_log = logging.getLogger(__name__) + +# Profile files already reported as still holding their key, so the notice is +# given once per process however many Profile objects load the file. +_legacy_notices: set[str] = set() +_legacy_notices_lock = threading.Lock() + def _write_private(path: Path, payload: dict[str, Any]) -> None: """Owner-only file, written atomically (no umask window, no torn reads).""" @@ -26,58 +38,70 @@ def _write_private(path: Path, payload: dict[str, Any]) -> None: os.replace(tmp, path) -def _initial_key(network: str) -> tuple[str, str]: - """(private_key, address) for a new profile. +def _selected_account_name(account: Optional[str]) -> str: + """The account name a lookup uses when the profile records none. - Imports ``SHIELD_SWAP_PRIVATE_KEY`` (or a path in - ``SHIELD_SWAP_PRIVATE_KEY_FILE``) when set — users with an existing - account supply their key out-of-band, never pasted into a conversation - — and generates a fresh random account otherwise. + The *account* argument, then ``ALEO_ACCOUNT`` (an empty value counts as + unset), then ``default``: the order the account keystore applies itself. """ - import aleo - net = getattr(aleo, network) - key = (os.environ.get("SHIELD_SWAP_PRIVATE_KEY") or "").strip() - key_file = os.environ.get("SHIELD_SWAP_PRIVATE_KEY_FILE") - if not key and key_file: - key = Path(key_file).read_text().strip() - pk = net.PrivateKey.from_string(key) if key else net.PrivateKey.random() - return str(pk), str(pk.address) + return account if account is not None else (os.environ.get("ALEO_ACCOUNT") or "default") + + +def _report_legacy_key(path: Path, address: str) -> None: + """Log, once per process and profile file, that the file still holds the key.""" + with _legacy_notices_lock: + if str(path) in _legacy_notices: + return + _legacy_notices.add(str(path)) + _log.warning( + "The private key of %s is still stored in %s; `python -m aleo.keystore migrate --from %s` " + "copies it into an account file shared by the Aleo tools (add --remove-legacy-key to take " + "it out of profile.json).", + address, path, path) class Profile: """A participant's persistent identity and credentials. - Holds exactly one Aleo address, generated on first use and reused every - session after. For several addresses, create a profile per address — each - needs its own home directory (``SHIELD_SWAP_HOME``, or *home* on - :meth:`load_or_create`), since the journal and credentials are per-profile - too. + Holds exactly one Aleo address, fixed when the profile is created and + reused every session after. For several addresses, create a profile per + address — each needs its own home directory (``SHIELD_SWAP_HOME``, or + *home* on :meth:`load_or_create`), since the journal and credentials are + per-profile too — and give each its own account name. - Load with :meth:`load_or_create`; the profile is created (with fresh key - material) when the home directory has none yet. The same call does both, - so callers never branch on whether one exists:: + Load with :meth:`load_or_create`. The same call serves the first run and + every later one, so callers never branch on whether a profile exists:: - from pathlib import Path from aleo_shield_swap import Profile - # First run: generates a key and writes it owner-only. + # First run: uses the stored Aleo account, or creates and stores one. profile = Profile.load_or_create() print(profile.address) # aleo1… - # Every run after: the same call returns that key, unchanged. + # Every run after: the same call returns that account, unchanged. assert Profile.load_or_create().address == profile.address - # A second address needs its own home; "~/..." is expanded. - other = Profile.load_or_create("~/.shield-swap-alt") + # A second address needs its own home and its own account name. + other = Profile.load_or_create("~/.shield-swap-alt", account="alt") - That last call generates a fresh key only when no key is being imported; - with ``SHIELD_SWAP_PRIVATE_KEY`` set, every new home adopts that one key - instead, so all of them share an address. + The private key is not in the profile. It is found through the Aleo + account keystore: the ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` + variables for a key supplied per run, otherwise the account file the + profile names. A key from the environment is used for the process and + never written to disk. Whichever source supplies it, the key must belong + to the profile's address. """ def __init__(self, home: Path, data: dict[str, Any]) -> None: self.home = home self._data = data + # How to find the key of an existing profile, as given to load_or_create(). + self._account: Optional[str] = None + self._accounts_dir: "Path | str | None" = None + self._password: Optional[str] = None + # The key, once resolved; one lookup serves the object's lifetime. + self._private_key: Optional[str] = None + self._key_lock = threading.Lock() def __repr__(self) -> str: return f"Profile({self.address!r}, home={str(self.home)!r})" @@ -99,39 +123,124 @@ def default_home() -> Path: @classmethod def load_or_create(cls, home: "Path | str | None" = None, *, network: str = "testnet", - endpoint: str = DEFAULT_ENDPOINT) -> "Profile": - """Load the profile at *home*, creating one with fresh keys if absent. - - Creating a profile writes a private key to disk at mode 600; an existing - profile file has its mode tightened to 600 on load, healing a loose one. - The key comes from ``SHIELD_SWAP_PRIVATE_KEY`` (or the file named by - ``SHIELD_SWAP_PRIVATE_KEY_FILE``) when set, so a user with an existing - account supplies it out-of-band rather than pasting it into a chat. - - *network* and *endpoint* apply only when creating — they are ignored for an - existing profile, which keeps the values it was created with. + endpoint: str = DEFAULT_ENDPOINT, + create: bool = True, + storage: str = "plaintext", + account: Optional[str] = None, + accounts_dir: "Path | str | None" = None, + password: Optional[str] = None, + save_password: bool = False) -> "Profile": + """Load the profile at *home*, binding one to an Aleo account if absent. + + A new profile takes the account the Aleo account keystore resolves: a + key in ``ALEO_PRIVATE_KEY`` or the file named by + ``ALEO_PRIVATE_KEY_FILE`` (``SHIELD_SWAP_PRIVATE_KEY`` and + ``SHIELD_SWAP_PRIVATE_KEY_FILE`` are aliases), otherwise the account + file selected by *account*. A user with an existing account supplies + it one of these ways rather than pasting a key into a chat. When + neither exists, a new account is created and stored in the keystore + with the chosen *storage*; pass ``create=False`` to raise instead. A + key from the environment is used for this process and never written + to disk, so it has to be supplied again on every later run. + + ``profile.json`` then records the address, the account name, the + network and the endpoint, at mode 600. It holds no private key. + + An existing profile is returned as recorded: *network*, *endpoint*, + *create*, *storage* and *save_password* apply only when creating. Its + key is looked up on the first read of :attr:`private_key`, using + *account*, *accounts_dir* and *password* as given here. A profile + written by an earlier release, with the key still in ``profile.json``, + keeps working unchanged. + + Reads the environment and the account file. Creating also writes the + account file and the profile, and for ``"keychain"`` or + ``"encrypted"`` storage writes the macOS Keychain or asks for a + password on an attached terminal. Does not contact a network. Args: home: Profile directory; defaults to :meth:`default_home`. network: Network to bind a NEW profile to. endpoint: API endpoint to record on a NEW profile. + create: Whether to create and store an account when a NEW profile + finds none. Defaults to True. + storage: How the keystore holds a newly created key: + ``"plaintext"`` (the default, a file only its owner can read), + ``"keychain"`` (the macOS login keychain) or ``"encrypted"`` + (under a password, on every system). ``"none"`` is rejected, + because nothing would hold the new key once the process exits. + account: Account name in the keystore. Defaults to + ``ALEO_ACCOUNT``, then the name the profile records, then + ``default``. + accounts_dir: Accounts directory. Defaults to + ``ALEO_ACCOUNTS_DIR``, then ``~/.aleo/accounts``. The profile + does not record it; pass it again on later runs. + password: Password of an ``"encrypted"`` account. Defaults to + ``ALEO_ACCOUNT_PASSWORD``, a password saved in the macOS + Keychain, then a hidden prompt on an attached terminal. + save_password: Also save the password of a newly created + ``"encrypted"`` account in the macOS Keychain, so later runs + need no password. Defaults to False. Returns: The loaded or newly created profile. + + Raises: + aleo.keystore.KeystoreError: Read ``code``. For a NEW profile: + ``ACCOUNT_NOT_FOUND`` when no account resolves and *create* is + False; ``UNSUPPORTED_STORAGE`` when an account would be + created with ``"none"`` or an unknown *storage*; + ``EMPTY_KEY_SOURCE``, ``KEY_CONFLICT`` or ``INVALID_KEY`` for + unusable key variables; ``ADDRESS_MISMATCH`` when a key from + the environment belongs to another address than the selected + account file; ``KEY_NOT_STORED`` when that file records an + address only and no key was supplied; ``PASSWORD_REQUIRED`` or + ``WRONG_PASSWORD`` for an encrypted account; + ``KEYCHAIN_UNAVAILABLE`` for ``"keychain"`` outside macOS; + ``INVALID_NAME`` for an unusable *account*. """ # expanduser: a "~/..." string is otherwise taken literally, creating a - # directory named ~ in the cwd and writing the private key there. + # directory named ~ in the cwd and writing the profile there. home = Path(home).expanduser() if home is not None else cls.default_home() path = home / _PROFILE if path.exists(): path.chmod(0o600) # heal a pre-existing loose mode - return cls(home, json.loads(path.read_text())) - home.mkdir(parents=True, exist_ok=True) - private_key, address = _initial_key(network) - data = {"address": address, "private_key": private_key, - "network": network, "endpoint": endpoint} - _write_private(path, data) - return cls(home, data) + profile = cls(home, json.loads(path.read_text())) + # The key is looked up when it is first read, with these options. + profile._account = account + profile._accounts_dir = accounts_dir + profile._password = password + else: + import aleo + from aleo import keystore + net = getattr(aleo, network) + try: + loaded = keystore.load(name=account, dir=accounts_dir, password=password) + private_key, address = loaded.private_key, loaded.address + # A key from the environment needs no account file; the name + # the lookup selected is recorded all the same. + name = loaded.stored.name if loaded.stored is not None else _selected_account_name(account) + except keystore.KeystoreError as error: + if error.code != "ACCOUNT_NOT_FOUND" or not create: + raise + if storage == "none": + raise keystore.KeystoreError( + "UNSUPPORTED_STORAGE", + 'A new account cannot be created with storage "none": nothing would hold its key ' + 'after this process exits. Choose "plaintext", "keychain" or "encrypted".', + ) from None + private_key = str(net.PrivateKey.random()) + stored = keystore.save(private_key, name=account, dir=accounts_dir, + storage=cast(Any, storage), # save() rejects an unknown value + password=password, save_password=save_password) + address, name = stored.address, stored.name + home.mkdir(parents=True, exist_ok=True) + data = {"address": address, "account": name, + "network": network, "endpoint": endpoint} + _write_private(path, data) + profile = cls(home, data) + profile._private_key = private_key + return profile # ── Identity ───────────────────────────────────────────────────────────── @@ -142,12 +251,62 @@ def address(self) -> str: @property def private_key(self) -> str: - """The profile's private key, read from disk. + """The private key of the profile's account. Whoever holds this controls the account and can decrypt its records — do not log it, echo it into a conversation, or send it to a service. + + The key is looked up on first use and kept for the lifetime of this + object: from ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when + set, otherwise from the account file named by the *account* argument + of :meth:`load_or_create`, then ``ALEO_ACCOUNT``, then the name the + profile records, then ``default``. A profile written by an earlier + release supplies the key still stored in ``profile.json`` when no + other source has one, and logs once how to move it. Whichever source + supplies the key, it must belong to :attr:`address`. + + The first read may run the macOS ``security`` tool or, for an + encrypted account, stretch a password (about 200 ms) and ask for it + on an attached terminal. + + Raises: + aleo.keystore.KeystoreError: Read ``code``. ``ADDRESS_MISMATCH`` + when the key found belongs to another address; the message + names both. ``ACCOUNT_NOT_FOUND`` when no source has a key, + such as a profile created from a key in the environment that + is no longer set. ``PASSWORD_REQUIRED`` when the account is + encrypted and no password was passed, set in + ``ALEO_ACCOUNT_PASSWORD``, saved in the Keychain or typed at + a terminal; ``WRONG_PASSWORD`` when it does not unlock the + key. ``EMPTY_KEY_SOURCE`` or ``KEY_CONFLICT`` for key + variables that are empty or disagree. """ - return self._data["private_key"] + if self._private_key is None: + with self._key_lock: + if self._private_key is None: + self._private_key = self._resolve_private_key() + return self._private_key + + def _resolve_private_key(self) -> str: + """Find the key of an existing profile through the account keystore.""" + from aleo import keystore + + # The keystore lets its name argument override ALEO_ACCOUNT, so the + # recorded name is passed only when neither the caller nor the + # variable selects an account. + name = self._account + if name is None and not os.environ.get("ALEO_ACCOUNT"): + name = self._data.get("account") + loaded = keystore.load( + name=name, dir=self._accounts_dir, + # Profiles written by earlier releases keep the key in the file. + legacy_key=self._data.get("private_key") or None, + expected_address=self.address, + password=self._password) + if loaded.source == "legacy": + _report_legacy_key(self.home / _PROFILE, self.address) + self._password = None # the key is held now; the password is not needed again + return loaded.private_key @property def network(self) -> str: diff --git a/shield-swap-sdk/tests/conftest.py b/shield-swap-sdk/tests/conftest.py index 909a8b83..7958f79e 100644 --- a/shield-swap-sdk/tests/conftest.py +++ b/shield-swap-sdk/tests/conftest.py @@ -8,9 +8,107 @@ """ from __future__ import annotations +import re +from pathlib import Path +from typing import Dict, List, Optional, Sequence, Tuple + import pytest -SLOT_TEXT = ("{ tick: 4055i32, tick_spacing: 60u32, " +# Variables a developer's shell could leak into a test: each one selects an +# account, a key, a password or a profile home. +ACCOUNT_VARIABLES = ( + "ALEO_PRIVATE_KEY", + "ALEO_PRIVATE_KEY_FILE", + "ALEO_ACCOUNT", + "ALEO_ACCOUNTS_DIR", + "ALEO_ACCOUNT_PASSWORD", + "SHIELD_SWAP_PRIVATE_KEY", + "SHIELD_SWAP_PRIVATE_KEY_FILE", + "SHIELD_SWAP_HOME", +) + + +class FakeKeychain: + """An in-memory stand-in for the macOS ``security`` tool. + + Understands the three invocations the account keystore makes (add, find + and delete a generic password), so Keychain storage can be exercised + without touching the login keychain of the machine running the tests. + """ + + def __init__(self) -> None: + self.entries: Dict[str, str] = {} + + def run(self, args: Sequence[str], stdin: Optional[str] = None) -> Tuple[Optional[int], str]: + args = list(args) + if args == ["-i"]: + match = re.fullmatch(r"add-generic-password -U -s (\S+) -a (\S+) -l (\S+) -w (\S+)\n", stdin or "") + if match is None: + return 1, "" + self.entries[f"{match.group(1)} {match.group(2)}"] = match.group(4) + return 0, "" + if len(args) == 6 and args[0] == "find-generic-password" and args[1] == "-s" and args[3] == "-a" and args[5] == "-w": + value = self.entries.get(f"{args[2]} {args[4]}") + return (44, "") if value is None else (0, f"{value}\n") + if len(args) == 5 and args[0] == "delete-generic-password" and args[1] == "-s" and args[3] == "-a": + return (44, "") if self.entries.pop(f"{args[2]} {args[4]}", None) is None else (0, "") + return 1, "" + + +class AccountSandbox: + """The replaced surroundings of one test. + + Attributes: + home: Stand-in home directory. The default accounts directory and the + default profile home resolve inside it. + accounts: The default accounts directory, ``/.aleo/accounts``. + Created by the keystore on first save. + keychain: The in-memory Keychain tool. + notes: Lines the keystore wrote to the terminal. + """ + + def __init__(self, home: Path) -> None: + self.home = home + self.accounts = home / ".aleo" / "accounts" + self.keychain = FakeKeychain() + self.notes: List[str] = [] + + +def _no_prompt(message: str) -> str: + raise AssertionError("unexpected prompt") + + +@pytest.fixture(autouse=True) +def account_sandbox(request: pytest.FixtureRequest, tmp_path_factory: pytest.TempPathFactory, + monkeypatch: pytest.MonkeyPatch) -> AccountSandbox: + """Keep every test away from the developer's own accounts, profile and Keychain. + + A profile finds its account through the account keystore, so a test that + only creates a profile would otherwise read or write ``~/.aleo/accounts``. + Each test gets an empty home directory, the account and profile variables + cleared, an in-memory Keychain and no terminal to prompt on. + """ + from aleo.keystore._runtime import runtime + + for name in ACCOUNT_VARIABLES: + monkeypatch.delenv(name, raising=False) + box = AccountSandbox(tmp_path_factory.mktemp("account-home")) + monkeypatch.setattr(runtime, "home", lambda: str(box.home)) + monkeypatch.setattr(runtime, "security", box.keychain.run) + monkeypatch.setattr(runtime, "terminal_attached", lambda: False) + monkeypatch.setattr(runtime, "prompt_hidden", _no_prompt) + monkeypatch.setattr(runtime, "prompt_visible", _no_prompt) + monkeypatch.setattr(runtime, "notify", box.notes.append) + # The live and devnode tiers keep the real home directory in the + # environment: local proving caches its parameters there. The keystore's + # own home lookup is replaced for them all the same. + if request.node.get_closest_marker("live") is None and request.node.get_closest_marker("devnode") is None: + monkeypatch.setenv("HOME", str(box.home)) + monkeypatch.setenv("USERPROFILE", str(box.home)) + return box + + +SLOT_TEXT =("{ tick: 4055i32, tick_spacing: 60u32, " "sqrt_price: { hi: 1u128, lo: 0u128 }, " "fee_protocol: 0u8, liquidity: 1000u128, " "fee_growth_global0_x_128: { hi: 0u128, lo: 0u128 }, " diff --git a/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py b/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py index ab715d49..62875c9c 100644 --- a/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py +++ b/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py @@ -25,7 +25,7 @@ def test_full_lifecycle_from_fresh_profile(tmp_path, monkeypatch): # Prove the participant path: credentials must SELF-provision and the # profile key must be genuinely fresh (a developer shell may carry - # SHIELD_SWAP_PRIVATE_KEY, which would import a funded, already-redeemed + # SHIELD_SWAP_PRIVATE_KEY, which would select a funded, already-redeemed # account and void every "fresh account" assertion below). monkeypatch.delenv("ALEO_E2E_API_KEY", raising=False) monkeypatch.delenv("ALEO_E2E_CONSUMER_ID", raising=False) diff --git a/shield-swap-sdk/tests/integration/test_swap_lifecycle.py b/shield-swap-sdk/tests/integration/test_swap_lifecycle.py index 50889f23..8be3039d 100644 --- a/shield-swap-sdk/tests/integration/test_swap_lifecycle.py +++ b/shield-swap-sdk/tests/integration/test_swap_lifecycle.py @@ -222,7 +222,7 @@ def test_concurrent_swaps_reserve_distinct_identities(tmp_path, monkeypatch): monkeypatch.setenv("ALEO_E2E_CONSUMER_ID", cid) monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", os.environ["ALEO_E2E_PRIVATE_KEY"]) dex = ShieldSwap.from_profile(tmp_path / "home") - report = dex.onboard() # imports the funded account; no-op stages skip + report = dex.onboard() # uses the funded account; no-op stages skip assert report.funded held = {tid: v for tid, v in dex.status().balances.items() if v.get("private", 0) > 0} diff --git a/shield-swap-sdk/tests/test_first_swap_account.py b/shield-swap-sdk/tests/test_first_swap_account.py index e1d1cc6a..a951e25c 100644 --- a/shield-swap-sdk/tests/test_first_swap_account.py +++ b/shield-swap-sdk/tests/test_first_swap_account.py @@ -1,4 +1,4 @@ -"""The runnable example saves generated keys before scanner or faucet I/O.""" +"""The runnable example binds its account before scanner or faucet I/O.""" import json import runpy from pathlib import Path @@ -11,21 +11,25 @@ EXAMPLE = Path(__file__).parents[1] / "examples/first-swap/swap.py" -def test_example_reuses_persisted_key_before_network(tmp_path, monkeypatch): - monkeypatch.delenv("SHIELD_SWAP_PRIVATE_KEY", raising=False) - monkeypatch.delenv("SHIELD_SWAP_PRIVATE_KEY_FILE", raising=False) +def test_example_reuses_stored_account_before_network(tmp_path, monkeypatch, account_sandbox): monkeypatch.setattr(Profile, "default_home", staticmethod(lambda: tmp_path)) # Stop at client construction, before registration/authentication/funding. monkeypatch.setattr("aleo.Aleo", Mock(side_effect=RuntimeError("stop before I/O"))) - for _ in range(2): + account_file = account_sandbox.accounts / "default.json" + for run in range(2): with pytest.raises(RuntimeError, match="stop before I/O"): runpy.run_path(str(EXAMPLE), run_name="__main__") saved = json.loads((tmp_path / "profile.json").read_text()) - if _ == 0: - first_key = saved["private_key"] - assert saved["private_key"] == first_key - assert saved["network"] == "testnet" + stored = json.loads(account_file.read_text()) + if run == 0: + first_address, first_account = saved["address"], account_file.read_bytes() + # The profile names the account; the key stays in the account file. + assert saved == {"address": first_address, "account": "default", "network": "testnet", + "endpoint": "https://edge.provable.com/api"} + assert stored["address"] == first_address and stored["key"]["type"] == "plaintext" + assert account_file.read_bytes() == first_account assert (tmp_path / "profile.json").stat().st_mode & 0o777 == 0o600 + assert account_file.stat().st_mode & 0o777 == 0o600 def test_example_uses_explicit_key_without_loading_profile(monkeypatch): diff --git a/shield-swap-sdk/tests/test_gen_context.py b/shield-swap-sdk/tests/test_gen_context.py index 16caf56e..f1e8aea2 100644 --- a/shield-swap-sdk/tests/test_gen_context.py +++ b/shield-swap-sdk/tests/test_gen_context.py @@ -66,4 +66,7 @@ def test_page_stays_compact(): # ``compliance_proofs`` parameter and a one-line note on what it takes. # 34k → 36k (2026-10-23) for record inventory: ``plan_inventory`` and # ``rebalance_inventory`` plus the reservation note on ``swap``. - assert len(_render()) < 36_000 + # 36k → 38k (2026-11-17) for the account keystore: ``from_profile`` says + # where the signer's key comes from and what it raises, and the + # existing-account question names the keystore import command. + assert len(_render()) < 38_000 diff --git a/shield-swap-sdk/tests/test_package.py b/shield-swap-sdk/tests/test_package.py index 5344b05f..fc1dd453 100644 --- a/shield-swap-sdk/tests/test_package.py +++ b/shield-swap-sdk/tests/test_package.py @@ -2,7 +2,7 @@ def test_version(): - assert aleo_shield_swap.__version__ == "0.8.0" + assert aleo_shield_swap.__version__ == "0.9.0" def test_lifecycle_exports(): @@ -32,7 +32,7 @@ def test_import_guard_names_the_aleo_sdk_upgrade(monkeypatch): import pytest import aleo_shield_swap - aleo_shield_swap._require_aleo_sdk() # the installed sdk has aleo.inventory - monkeypatch.setitem(sys.modules, "aleo.inventory", None) # simulate an aleo-sdk without it - with pytest.raises(ImportError, match=r'needs aleo-sdk>=0\.8\.0 \(found .*\); run: pip install -U "aleo-sdk>=0\.8\.0"'): + aleo_shield_swap._require_aleo_sdk() # the installed sdk has aleo.keystore + monkeypatch.setitem(sys.modules, "aleo.keystore", None) # simulate an aleo-sdk without it + with pytest.raises(ImportError, match=r'needs aleo-sdk>=0\.9\.0 \(found .*\); run: pip install -U "aleo-sdk>=0\.9\.0"'): aleo_shield_swap._require_aleo_sdk() diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index 68d93cab..f0e52101 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -1,7 +1,122 @@ +"""The profile binds one Aleo account and finds its key through ``aleo.keystore``. + +Every test runs inside the ``account_sandbox`` fixture (``conftest.py``): an +empty home directory, the account and profile variables cleared, an in-memory +Keychain and no terminal. Keys are random and never funded; comparisons go +through ``same_secret`` so a failure never prints one. +""" +from __future__ import annotations + +import json +import logging import stat +from pathlib import Path +from types import SimpleNamespace +from typing import Any, Callable +from unittest.mock import Mock + +import pytest +from aleo import keystore, testnet +from aleo.keystore import KeystoreError + +from aleo_shield_swap import ShieldSwap +from aleo_shield_swap import profile as profile_module +from aleo_shield_swap.profile import DEFAULT_ENDPOINT, Profile + +# Test-only passwords. Never used for a funded account. +PASSWORD = "correct horse battery staple" +OTHER_PASSWORD = "another test password" + + +def new_account() -> SimpleNamespace: + """A random account as an address and private-key pair of strings.""" + key = testnet.PrivateKey.random() + return SimpleNamespace(address=str(key.address), private_key=str(key)) + + +def same_secret(actual: object, expected: object) -> None: + """Compare two secrets without putting either into an assertion message.""" + if not isinstance(actual, str) or actual != expected: + raise AssertionError("the secret values differ") + + +def failure(call: Callable[[], Any]) -> KeystoreError: + """The keystore error a call fails with.""" + try: + call() + except KeystoreError as error: + return error + raise AssertionError("expected the call to fail") + + +def mode(path: Path) -> int: + return stat.S_IMODE(path.stat().st_mode) + + +def files_under(*roots: Path) -> list[Path]: + return [path for root in roots if root.exists() for path in root.rglob("*") if path.is_file()] + + +def assert_key_on_no_disk(private_key: str, *roots: Path) -> None: + """No file under *roots* contains the key.""" + for path in files_under(*roots): + if private_key.encode() in path.read_bytes(): + raise AssertionError(f"{path} contains a private key") + + +def saved_profile(home: Path) -> dict[str, Any]: + return json.loads((home / "profile.json").read_text()) + + +def write_legacy_profile(home: Path, account: SimpleNamespace, **extra: Any) -> Path: + """A profile as earlier releases wrote it: the key inside ``profile.json``.""" + home.mkdir(parents=True, exist_ok=True) + path = home / "profile.json" + data = {"address": account.address, "private_key": account.private_key, + "network": "testnet", "endpoint": DEFAULT_ENDPOINT, **extra} + path.write_text(json.dumps(data, indent=1)) + path.chmod(0o600) + return path + + +@pytest.fixture(autouse=True) +def fresh_legacy_notices(monkeypatch): + """The legacy-key notice is given once per process; start each test unnotified.""" + monkeypatch.setattr(profile_module, "_legacy_notices", set()) -from aleo_shield_swap.profile import Profile +@pytest.fixture +def lookups(monkeypatch): + """Count the keystore lookups a test triggers.""" + calls: list[dict[str, Any]] = [] + real = keystore.load + + def counted(**kwargs: Any): + calls.append(kwargs) + return real(**kwargs) + + monkeypatch.setattr(keystore, "load", counted) + return calls + + +# ── The test surroundings themselves ───────────────────────────────────────── + +def test_tests_run_against_a_stand_in_home(account_sandbox, tmp_path): + """Guards the guard: nothing here may resolve to the developer's own files.""" + import os + + assert Path.home() == account_sandbox.home + assert Profile.default_home() == account_sandbox.home / ".shield-swap" + for name in ("ALEO_PRIVATE_KEY", "ALEO_PRIVATE_KEY_FILE", "ALEO_ACCOUNT", "ALEO_ACCOUNTS_DIR", + "ALEO_ACCOUNT_PASSWORD", "SHIELD_SWAP_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY_FILE", + "SHIELD_SWAP_HOME"): + assert name not in os.environ + assert keystore.info() is None + stored = keystore.save(new_account().private_key) + assert stored.path == account_sandbox.accounts / "default.json" + + +# ── A home with no profile yet ─────────────────────────────────────────────── def test_create_then_reload_is_stable(tmp_path): p1 = Profile.load_or_create(tmp_path / "home") @@ -9,14 +124,591 @@ def test_create_then_reload_is_stable(tmp_path): assert p1.private_key.startswith("APrivateKey1") assert p1.network == "testnet" p2 = Profile.load_or_create(tmp_path / "home") # reload, no regen - assert (p2.address, p2.private_key) == (p1.address, p1.private_key) + assert p2.address == p1.address + same_secret(p2.private_key, p1.private_key) + + +def test_new_profile_stores_the_key_in_the_account_file_not_the_profile(tmp_path, account_sandbox): + profile = Profile.load_or_create(tmp_path / "home", network="mainnet", endpoint="https://node.example") + saved = saved_profile(profile.home) + assert saved == {"address": profile.address, "account": "default", + "network": "mainnet", "endpoint": "https://node.example"} + assert_key_on_no_disk(profile.private_key, tmp_path) + + account_file = account_sandbox.accounts / "default.json" + stored = json.loads(account_file.read_text()) + assert stored["address"] == profile.address + assert stored["key"]["type"] == "plaintext" + same_secret(stored["key"]["privateKey"], profile.private_key) + assert mode(account_file) == 0o600 + assert keystore.info() == keystore.StoredAccount( + name="default", path=account_file, address=profile.address, storage="plaintext") -def test_key_file_is_owner_only(tmp_path): +def test_profile_file_is_owner_only(tmp_path): p = Profile.load_or_create(tmp_path / "home") - mode = stat.S_IMODE((p.home / "profile.json").stat().st_mode) - assert mode == 0o600 + assert mode(p.home / "profile.json") == 0o600 + + +def test_loose_profile_mode_is_tightened_on_load(tmp_path): + p = Profile.load_or_create(tmp_path / "home") + (p.home / "profile.json").chmod(0o644) + Profile.load_or_create(tmp_path / "home") + assert mode(p.home / "profile.json") == 0o600 + + +def test_new_profile_adopts_the_stored_account(tmp_path, account_sandbox): + account = new_account() + keystore.save(account.private_key) + before = (account_sandbox.accounts / "default.json").read_bytes() + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == account.address + same_secret(profile.private_key, account.private_key) + assert (account_sandbox.accounts / "default.json").read_bytes() == before + assert saved_profile(profile.home)["account"] == "default" + + +def test_two_homes_share_the_stored_account(tmp_path): + first = Profile.load_or_create(tmp_path / "one") + second = Profile.load_or_create(tmp_path / "two") + assert second.address == first.address + + +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY"]) +def test_key_from_the_environment_is_used_and_never_written(tmp_path, monkeypatch, account_sandbox, variable): + account = new_account() + monkeypatch.setenv(variable, account.private_key) + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == account.address + same_secret(profile.private_key, account.private_key) + assert saved_profile(profile.home) == {"address": account.address, "account": "default", + "network": "testnet", "endpoint": DEFAULT_ENDPOINT} + assert not account_sandbox.accounts.exists() + assert_key_on_no_disk(account.private_key, tmp_path, account_sandbox.home) + + +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY_FILE", "SHIELD_SWAP_PRIVATE_KEY_FILE"]) +def test_key_file_from_the_environment_is_used_and_never_copied(tmp_path, monkeypatch, account_sandbox, variable): + account = new_account() + key_file = tmp_path / "key.txt" + key_file.write_text(account.private_key + "\n") + monkeypatch.setenv(variable, str(key_file)) + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == account.address + same_secret(profile.private_key, account.private_key) + assert not account_sandbox.accounts.exists() + assert_key_on_no_disk(account.private_key, tmp_path / "home", account_sandbox.home) + + +def test_profile_made_from_an_environment_key_needs_it_again(tmp_path, monkeypatch): + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + Profile.load_or_create(tmp_path / "home") + monkeypatch.delenv("ALEO_PRIVATE_KEY") + + later = Profile.load_or_create(tmp_path / "home") # loading still works + assert later.address == account.address + assert failure(lambda: later.private_key).code == "ACCOUNT_NOT_FOUND" + + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + + +def test_environment_key_must_match_the_selected_account_file(tmp_path, monkeypatch): + stored, supplied = new_account(), new_account() + keystore.save(stored.private_key) + monkeypatch.setenv("ALEO_PRIVATE_KEY", supplied.private_key) + error = failure(lambda: Profile.load_or_create(tmp_path / "home")) + assert error.code == "ADDRESS_MISMATCH" + assert stored.address in str(error) and supplied.address in str(error) + assert not (tmp_path / "home").exists() + + +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY"]) +def test_empty_key_variable_is_an_error_not_a_new_account(tmp_path, monkeypatch, account_sandbox, variable): + monkeypatch.setenv(variable, "") + assert failure(lambda: Profile.load_or_create(tmp_path / "home")).code == "EMPTY_KEY_SOURCE" + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_empty_key_file_is_an_error_not_a_new_account(tmp_path, monkeypatch, account_sandbox): + key_file = tmp_path / "key.txt" + key_file.write_text("\n") + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY_FILE", str(key_file)) + assert failure(lambda: Profile.load_or_create(tmp_path / "home")).code == "EMPTY_KEY_SOURCE" + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_variables_holding_different_keys_are_an_error(tmp_path, monkeypatch): + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", new_account().private_key) + assert failure(lambda: Profile.load_or_create(tmp_path / "home")).code == "KEY_CONFLICT" + assert not (tmp_path / "home").exists() + + +def test_create_false_raises_when_no_account_resolves(tmp_path, account_sandbox): + error = failure(lambda: Profile.load_or_create(tmp_path / "home", create=False)) + assert error.code == "ACCOUNT_NOT_FOUND" + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_create_false_uses_an_account_that_resolves(tmp_path, monkeypatch): + stored = new_account() + keystore.save(stored.private_key) + assert Profile.load_or_create(tmp_path / "stored", create=False).address == stored.address + + supplied = new_account() + monkeypatch.setenv("ALEO_ACCOUNT", "per-run") + monkeypatch.setenv("ALEO_PRIVATE_KEY", supplied.private_key) + assert Profile.load_or_create(tmp_path / "supplied", create=False).address == supplied.address + + +def test_creating_without_a_stored_key_is_rejected(tmp_path, account_sandbox): + error = failure(lambda: Profile.load_or_create(tmp_path / "home", storage="none")) + assert error.code == "UNSUPPORTED_STORAGE" + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_storage_none_is_only_rejected_when_an_account_would_be_created(tmp_path, monkeypatch): + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + assert Profile.load_or_create(tmp_path / "home", storage="none").address == account.address + + +def test_unknown_storage_is_rejected_before_anything_is_written(tmp_path, account_sandbox): + error = failure(lambda: Profile.load_or_create(tmp_path / "home", storage="vault")) + assert error.code == "UNSUPPORTED_STORAGE" + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_unknown_network_is_rejected_before_anything_is_written(tmp_path, account_sandbox): + with pytest.raises(AttributeError): + Profile.load_or_create(tmp_path / "home", network="nonet") + assert not (tmp_path / "home").exists() + assert not account_sandbox.accounts.exists() + + +def test_account_argument_names_the_account_file(tmp_path, account_sandbox): + profile = Profile.load_or_create(tmp_path / "home", account="trading") + assert saved_profile(profile.home)["account"] == "trading" + assert (account_sandbox.accounts / "trading.json").exists() + assert not (account_sandbox.accounts / "default.json").exists() + + +def test_account_variable_names_the_account_file(tmp_path, monkeypatch, account_sandbox): + monkeypatch.setenv("ALEO_ACCOUNT", "from-env") + profile = Profile.load_or_create(tmp_path / "home") + assert saved_profile(profile.home)["account"] == "from-env" + assert (account_sandbox.accounts / "from-env.json").exists() + + +@pytest.mark.parametrize("argument, variable, recorded", [ + (None, None, "default"), (None, "from-env", "from-env"), ("from-argument", "from-env", "from-argument"), +]) +def test_selected_name_is_recorded_when_the_key_comes_from_the_environment( + tmp_path, monkeypatch, account_sandbox, argument, variable, recorded): + """No account file exists for a key supplied per run; the name the lookup selected is kept.""" + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + if variable is not None: + monkeypatch.setenv("ALEO_ACCOUNT", variable) + profile = Profile.load_or_create(tmp_path / "home", account=argument) + assert saved_profile(profile.home)["account"] == recorded + assert not account_sandbox.accounts.exists() + + +def test_account_argument_beats_the_variable_when_creating(tmp_path, monkeypatch, account_sandbox): + monkeypatch.setenv("ALEO_ACCOUNT", "from-env") + profile = Profile.load_or_create(tmp_path / "home", account="from-argument") + assert saved_profile(profile.home)["account"] == "from-argument" + assert [path.name for path in account_sandbox.accounts.iterdir()] == ["from-argument.json"] + + +def test_invalid_account_name_is_rejected(tmp_path, account_sandbox): + assert failure(lambda: Profile.load_or_create(tmp_path / "home", account="Not Valid")).code == "INVALID_NAME" + assert not (tmp_path / "home").exists() + + +def test_accounts_dir_is_used_and_not_recorded(tmp_path, account_sandbox): + accounts = tmp_path / "accounts" + profile = Profile.load_or_create(tmp_path / "home", accounts_dir=accounts) + assert (accounts / "default.json").exists() + assert not account_sandbox.accounts.exists() + assert set(saved_profile(profile.home)) == {"address", "account", "network", "endpoint"} + + # The directory is not recorded, so a later run passes it again. + same_secret(Profile.load_or_create(tmp_path / "home", accounts_dir=accounts).private_key, profile.private_key) + without = Profile.load_or_create(tmp_path / "home") + assert failure(lambda: without.private_key).code == "ACCOUNT_NOT_FOUND" + + +def test_accounts_dir_variable_is_honoured(tmp_path, monkeypatch, account_sandbox): + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", str(tmp_path / "from-env")) + profile = Profile.load_or_create(tmp_path / "home") + assert (tmp_path / "from-env" / "default.json").exists() + assert not account_sandbox.accounts.exists() + same_secret(Profile.load_or_create(tmp_path / "home").private_key, profile.private_key) + +# ── Encrypted and Keychain storage ─────────────────────────────────────────── + +def test_encrypted_account_needs_its_password_on_later_runs(tmp_path, monkeypatch, account_sandbox): + created = Profile.load_or_create(tmp_path / "home", storage="encrypted", password=PASSWORD) + stored = json.loads((account_sandbox.accounts / "default.json").read_text()) + assert stored["key"]["type"] == "encrypted" + assert_key_on_no_disk(created.private_key, tmp_path, account_sandbox.home) + + # Loading never needs the password; reading the key does. + locked = Profile.load_or_create(tmp_path / "home") + assert locked.address == created.address + assert failure(lambda: locked.private_key).code == "PASSWORD_REQUIRED" + + same_secret(Profile.load_or_create(tmp_path / "home", password=PASSWORD).private_key, created.private_key) + wrong = Profile.load_or_create(tmp_path / "home", password=OTHER_PASSWORD) + assert failure(lambda: wrong.private_key).code == "WRONG_PASSWORD" + + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + + +def test_encrypted_account_takes_its_password_from_the_variable_when_created(tmp_path, monkeypatch, account_sandbox): + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + created = Profile.load_or_create(tmp_path / "home", storage="encrypted") + same_secret(keystore.export(password=PASSWORD), created.private_key) + + +def test_encrypted_account_without_a_password_source_creates_nothing(tmp_path, account_sandbox): + error = failure(lambda: Profile.load_or_create(tmp_path / "home", storage="encrypted")) + assert error.code == "PASSWORD_REQUIRED" + assert not (tmp_path / "home").exists() + assert files_under(account_sandbox.home) == [] + + +def test_new_profile_adopts_an_encrypted_account(tmp_path): + account = new_account() + keystore.save(account.private_key, storage="encrypted", password=PASSWORD) + assert failure(lambda: Profile.load_or_create(tmp_path / "locked")).code == "PASSWORD_REQUIRED" + assert not (tmp_path / "locked").exists() + profile = Profile.load_or_create(tmp_path / "home", password=PASSWORD) + assert profile.address == account.address + same_secret(profile.private_key, account.private_key) + + +def test_saved_password_unlocks_later_runs(tmp_path, monkeypatch, account_sandbox): + from aleo.keystore._runtime import runtime + monkeypatch.setattr(runtime, "platform", "darwin") + created = Profile.load_or_create(tmp_path / "home", storage="encrypted", + password=PASSWORD, save_password=True) + assert [entry.split()[0] for entry in account_sandbox.keychain.entries] == ["aleo-account-password"] + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + + +def test_keychain_storage_keeps_the_key_out_of_every_file(tmp_path, monkeypatch, account_sandbox): + from aleo.keystore._runtime import runtime + monkeypatch.setattr(runtime, "platform", "darwin") + created = Profile.load_or_create(tmp_path / "home", storage="keychain") + stored = json.loads((account_sandbox.accounts / "default.json").read_text()) + assert stored["key"]["type"] == "keychain" + assert_key_on_no_disk(created.private_key, tmp_path, account_sandbox.home) + (entry, value), = account_sandbox.keychain.entries.items() + assert entry == f"aleo-account-key {stored['key']['account']}" + same_secret(value, created.private_key) + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + + +def test_keychain_storage_outside_macos_creates_nothing(tmp_path, monkeypatch, account_sandbox): + from aleo.keystore._runtime import runtime + monkeypatch.setattr(runtime, "platform", "linux") + error = failure(lambda: Profile.load_or_create(tmp_path / "home", storage="keychain")) + assert error.code == "KEYCHAIN_UNAVAILABLE" + assert not (tmp_path / "home").exists() + assert files_under(account_sandbox.home) == [] + assert account_sandbox.keychain.entries == {} + + +# ── An existing profile ────────────────────────────────────────────────────── + +def test_legacy_profile_keeps_working_and_is_left_untouched(tmp_path, account_sandbox): + account = new_account() + path = write_legacy_profile(tmp_path / "home", account) + before = path.read_bytes() + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == account.address + same_secret(profile.private_key, account.private_key) + assert profile.network == "testnet" and profile.endpoint == DEFAULT_ENDPOINT + assert path.read_bytes() == before + assert not account_sandbox.accounts.exists() + + +def test_legacy_profile_is_reported_once(tmp_path, caplog): + account = new_account() + path = write_legacy_profile(tmp_path / "home", account) + with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): + first = Profile.load_or_create(tmp_path / "home") + assert caplog.records == [] # nothing until the key is read + first.private_key + first.private_key + Profile.load_or_create(tmp_path / "home").private_key + (record,) = caplog.records + assert record.levelno == logging.WARNING and record.name == "aleo_shield_swap.profile" + message = record.getMessage() + assert f"python -m aleo.keystore migrate --from {path}" in message + assert account.address in message and str(path) in message + if account.private_key in message or account.private_key in caplog.text: + raise AssertionError("the notice contains a private key") + + +def test_each_legacy_profile_is_reported(tmp_path, caplog): + with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): + for name in ("one", "two"): + write_legacy_profile(tmp_path / name, new_account()) + Profile.load_or_create(tmp_path / name).private_key + assert len(caplog.records) == 2 + + +def test_migrated_legacy_profile_reads_the_account_file_without_a_notice(tmp_path, caplog, account_sandbox): + account = new_account() + path = write_legacy_profile(tmp_path / "home", account) + keystore.migrate(path) # the copy in profile.json stays + with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + assert caplog.records == [] + + keystore.migrate(path, remove_legacy_key=True) + assert "private_key" not in saved_profile(tmp_path / "home") + assert_key_on_no_disk(account.private_key, tmp_path) + with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + assert caplog.records == [] + + +def test_legacy_profile_with_the_same_key_in_the_environment_gives_no_notice(tmp_path, monkeypatch, caplog): + account = new_account() + write_legacy_profile(tmp_path / "home", account) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", account.private_key) + with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + assert caplog.records == [] + + +@pytest.mark.parametrize("legacy", [True, False]) +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY", "ALEO_PRIVATE_KEY_FILE"]) +def test_environment_key_for_another_account_is_an_error(tmp_path, monkeypatch, legacy, variable): + other = new_account() + if legacy: + bound = new_account() + write_legacy_profile(tmp_path / "home", bound) + else: + bound = SimpleNamespace(address=Profile.load_or_create(tmp_path / "home").address) + value = other.private_key + if variable.endswith("_FILE"): + (tmp_path / "other.key").write_text(other.private_key) + value = str(tmp_path / "other.key") + monkeypatch.setenv(variable, value) + + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == bound.address + error = failure(lambda: profile.private_key) + assert error.code == "ADDRESS_MISMATCH" + assert bound.address in str(error) and other.address in str(error) + if other.private_key in str(error): + raise AssertionError("the error contains a private key") + + +def test_environment_key_for_the_same_account_is_used(tmp_path, monkeypatch): + created = Profile.load_or_create(tmp_path / "home") + key = created.private_key + monkeypatch.setenv("ALEO_PRIVATE_KEY", key) + same_secret(Profile.load_or_create(tmp_path / "home").private_key, key) + assert keystore.load(expected_address=created.address).source == "env" + + +def test_empty_key_variable_is_an_error_for_an_existing_profile(tmp_path, monkeypatch): + Profile.load_or_create(tmp_path / "home") + monkeypatch.setenv("ALEO_PRIVATE_KEY", "") + profile = Profile.load_or_create(tmp_path / "home") + assert failure(lambda: profile.private_key).code == "EMPTY_KEY_SOURCE" + + +def test_account_file_for_another_address_is_an_error(tmp_path, account_sandbox): + profile = Profile.load_or_create(tmp_path / "home") + (account_sandbox.accounts / "default.json").unlink() + other = new_account() + keystore.save(other.private_key) + reloaded = Profile.load_or_create(tmp_path / "home") + error = failure(lambda: reloaded.private_key) + assert error.code == "ADDRESS_MISMATCH" + assert profile.address in str(error) and other.address in str(error) + + +def test_legacy_key_must_match_an_account_file_of_the_same_name(tmp_path): + legacy, other = new_account(), new_account() + write_legacy_profile(tmp_path / "home", legacy) + keystore.save(other.private_key) + profile = Profile.load_or_create(tmp_path / "home") + error = failure(lambda: profile.private_key) + assert error.code == "ADDRESS_MISMATCH" + assert legacy.address in str(error) and other.address in str(error) + + +def test_address_only_account_file_needs_the_key_from_the_environment(tmp_path, monkeypatch): + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + keystore.save(account.private_key, storage="none") + Profile.load_or_create(tmp_path / "home") + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + monkeypatch.delenv("ALEO_PRIVATE_KEY") + profile = Profile.load_or_create(tmp_path / "home") + assert failure(lambda: profile.private_key).code == "KEY_NOT_STORED" + + +# ── Which account name an existing profile selects ─────────────────────────── + +def test_recorded_account_name_is_used(tmp_path, lookups): + created = Profile.load_or_create(tmp_path / "home", account="trading") + del lookups[:] + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + assert [call["name"] for call in lookups] == ["trading"] + + +def test_account_variable_beats_the_recorded_name(tmp_path, monkeypatch, account_sandbox, lookups): + created = Profile.load_or_create(tmp_path / "home", account="trading") + monkeypatch.setenv("ALEO_ACCOUNT", "elsewhere") + del lookups[:] + profile = Profile.load_or_create(tmp_path / "home") + error = failure(lambda: profile.private_key) + assert error.code == "ACCOUNT_NOT_FOUND" and "elsewhere.json" in str(error) + # The recorded name is withheld so the keystore applies the variable itself. + assert [call["name"] for call in lookups] == [None] + + # A second account file holding the same key satisfies the address check. + keystore.save(created.private_key, name="elsewhere") + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + + # One holding another key does not. + monkeypatch.setenv("ALEO_ACCOUNT", "stranger") + keystore.save(new_account().private_key, name="stranger") + stranger = Profile.load_or_create(tmp_path / "home") + assert failure(lambda: stranger.private_key).code == "ADDRESS_MISMATCH" + + +def test_account_argument_beats_the_variable_and_the_recorded_name(tmp_path, monkeypatch, lookups): + created = Profile.load_or_create(tmp_path / "home", account="trading") + keystore.save(created.private_key, name="copy") + monkeypatch.setenv("ALEO_ACCOUNT", "missing") + del lookups[:] + same_secret(Profile.load_or_create(tmp_path / "home", account="copy").private_key, created.private_key) + assert [call["name"] for call in lookups] == ["copy"] + + +def test_empty_account_variable_counts_as_unset(tmp_path, monkeypatch, lookups): + created = Profile.load_or_create(tmp_path / "home", account="trading") + monkeypatch.setenv("ALEO_ACCOUNT", "") + del lookups[:] + same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) + assert [call["name"] for call in lookups] == ["trading"] + + +def test_profile_without_a_recorded_name_selects_default(tmp_path, lookups): + account = new_account() + path = write_legacy_profile(tmp_path / "home", account) + keystore.migrate(path, remove_legacy_key=True) + del lookups[:] + same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) + assert [call["name"] for call in lookups] == [None] + + +def test_lookup_passes_the_recorded_address_and_the_legacy_key(tmp_path, lookups): + account = new_account() + write_legacy_profile(tmp_path / "home", account) + Profile.load_or_create(tmp_path / "home", accounts_dir=tmp_path / "accounts", password=PASSWORD).private_key + (call,) = lookups + assert call["expected_address"] == account.address + same_secret(call["legacy_key"], account.private_key) + assert call["dir"] == tmp_path / "accounts" + same_secret(call["password"], PASSWORD) + + +# ── One lookup per profile object ──────────────────────────────────────────── + +def test_key_is_resolved_once_per_object_and_only_when_read(tmp_path, lookups): + Profile.load_or_create(tmp_path / "home") + del lookups[:] + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address and profile.network and profile.credentials == {} + assert lookups == [] # loading reads no key + for _ in range(3): + profile.private_key + assert len(lookups) == 1 + Profile.load_or_create(tmp_path / "home").private_key # a new object looks again + assert len(lookups) == 2 + + +def test_new_profile_keeps_the_key_it_was_created_with(tmp_path, lookups): + profile = Profile.load_or_create(tmp_path / "home", storage="encrypted", password=PASSWORD) + assert len(lookups) == 1 # the lookup that found no account + profile.private_key + profile.private_key + assert len(lookups) == 1 + + +def test_failed_lookup_is_retried(tmp_path, monkeypatch): + created = Profile.load_or_create(tmp_path / "home", storage="encrypted", password=PASSWORD) + profile = Profile.load_or_create(tmp_path / "home") + assert failure(lambda: profile.private_key).code == "PASSWORD_REQUIRED" + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + same_secret(profile.private_key, created.private_key) + + +def test_creation_arguments_are_ignored_for_an_existing_profile(tmp_path, account_sandbox): + created = Profile.load_or_create(tmp_path / "home") + again = Profile.load_or_create(tmp_path / "home", network="mainnet", endpoint="https://other.example", + create=False, storage="none", save_password=True) + assert (again.address, again.network, again.endpoint) == (created.address, "testnet", DEFAULT_ENDPOINT) + same_secret(again.private_key, created.private_key) + assert [path.name for path in account_sandbox.accounts.iterdir()] == ["default.json"] + + +def test_repr_and_saved_profile_hold_no_key(tmp_path): + profile = Profile.load_or_create(tmp_path / "home") + key = profile.private_key + if key in repr(profile) or key in (profile.home / "profile.json").read_text(): + raise AssertionError("the profile exposes a private key") + + +# ── Callers ────────────────────────────────────────────────────────────────── + +def test_from_profile_signs_with_the_resolved_key(tmp_path, monkeypatch): + account = new_account() + keystore.save(account.private_key, storage="encrypted", password=PASSWORD) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + aleo = Mock() + aleo.network_name = "testnet" + monkeypatch.setattr("aleo.Aleo", Mock(return_value=aleo)) + monkeypatch.setattr("aleo.HTTPProvider", Mock()) + + dex = ShieldSwap.from_profile(tmp_path / "home") + + (bound,), _ = aleo.account.from_private_key.call_args + same_secret(bound, account.private_key) + assert dex.profile.address == account.address + assert dex.journal.path == tmp_path / "home" / "journal.jsonl" + assert saved_profile(tmp_path / "home")["account"] == "default" + + +def test_from_profile_reports_a_locked_account(tmp_path, monkeypatch): + keystore.save(new_account().private_key, storage="encrypted", password=PASSWORD) + monkeypatch.setattr("aleo.Aleo", Mock()) + monkeypatch.setattr("aleo.HTTPProvider", Mock()) + assert failure(lambda: ShieldSwap.from_profile(tmp_path / "home")).code == "PASSWORD_REQUIRED" + assert not (tmp_path / "home").exists() + + +# ── Homes, credentials and the journal are unchanged ───────────────────────── def test_env_home_override(tmp_path, monkeypatch): monkeypatch.setenv("SHIELD_SWAP_HOME", str(tmp_path / "envhome")) @@ -24,6 +716,12 @@ def test_env_home_override(tmp_path, monkeypatch): assert p.home == tmp_path / "envhome" +def test_default_home_is_under_the_home_directory(account_sandbox): + p = Profile.load_or_create() + assert p.home == account_sandbox.home / ".shield-swap" + assert (account_sandbox.home / ".shield-swap" / "profile.json").exists() + + def test_credentials_roundtrip(tmp_path): p = Profile.load_or_create(tmp_path / "home") assert p.credentials == {} @@ -32,8 +730,7 @@ def test_credentials_roundtrip(tmp_path): p2 = Profile.load_or_create(tmp_path / "home") assert p2.credentials == {"jwt": "j", "dps_api_key": "k", "dps_consumer_id": "c"} - mode = stat.S_IMODE((p.home / "credentials.json").stat().st_mode) - assert mode == 0o600 + assert mode(p.home / "credentials.json") == 0o600 def test_journal_path(tmp_path): @@ -41,32 +738,9 @@ def test_journal_path(tmp_path): assert p.journal_path == p.home / "journal.jsonl" -def test_existing_key_imported_from_env(tmp_path, monkeypatch): - import aleo - pk = aleo.testnet.PrivateKey.random() - monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", str(pk)) - p = Profile.load_or_create(tmp_path / "home") - assert p.private_key == str(pk) - assert p.address == str(pk.address) - - -def test_existing_key_imported_from_file(tmp_path, monkeypatch): - import aleo - pk = aleo.testnet.PrivateKey.random() - key_file = tmp_path / "key.txt" - key_file.write_text(str(pk) + "\n") - monkeypatch.delenv("SHIELD_SWAP_PRIVATE_KEY", raising=False) - monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY_FILE", str(key_file)) - p = Profile.load_or_create(tmp_path / "home") - assert p.address == str(pk.address) - - def test_tilde_in_home_is_expanded(tmp_path, monkeypatch): """A "~/..." string must not create a literal ~ directory in the cwd — - that would write the private key somewhere no later run looks.""" - from pathlib import Path - from aleo_shield_swap.profile import Profile - + that would write the profile somewhere no later run looks.""" monkeypatch.setenv("HOME", str(tmp_path)) monkeypatch.chdir(tmp_path) profile = Profile.load_or_create("~/.shield-swap-tilde") @@ -75,8 +749,6 @@ def test_tilde_in_home_is_expanded(tmp_path, monkeypatch): def test_tilde_in_shield_swap_home_is_expanded(tmp_path, monkeypatch): - from aleo_shield_swap.profile import Profile - monkeypatch.setenv("HOME", str(tmp_path)) monkeypatch.setenv("SHIELD_SWAP_HOME", "~/from-env") monkeypatch.chdir(tmp_path) From 07539dc9d015af8a944692cbe83cbcd14f7cd1af Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 09:49:46 -0500 Subject: [PATCH 2/9] docs(shield-swap): bring the profile docstrings in line with the voice guide Docstrings and comments only; no code changes. - Describe the current contract instead of release history: a profile whose profile.json holds a private key, not one "written by an earlier release". - Explain each storage choice by what it costs on later runs. - Move the errors of ShieldSwap.from_profile() into a Raises section, and regenerate the agent guide from it. - Lead helper docstrings with a verb. --- shield-swap-sdk/AGENTS.md | 17 +++--- .../python/aleo_shield_swap/AGENTS.md | 17 +++--- .../python/aleo_shield_swap/client.py | 17 +++--- .../python/aleo_shield_swap/profile.py | 54 ++++++++++--------- shield-swap-sdk/tests/conftest.py | 4 +- shield-swap-sdk/tests/test_profile.py | 14 ++--- 6 files changed, 69 insertions(+), 54 deletions(-) diff --git a/shield-swap-sdk/AGENTS.md b/shield-swap-sdk/AGENTS.md index 7a119be4..f57704a3 100644 --- a/shield-swap-sdk/AGENTS.md +++ b/shield-swap-sdk/AGENTS.md @@ -32,7 +32,7 @@ credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run The signer is the profile's Aleo account, found through the account keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in -``~/.aleo/accounts`` that the profile names. A fresh profile adopts +``~/.aleo/accounts`` that the profile names. A fresh profile uses that account, or creates one and stores it there; the profile itself holds no private key, and a key from the environment is never written to disk. To create the account encrypted, in the macOS Keychain or @@ -44,12 +44,6 @@ 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. -Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key -cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address -than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account -with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an -existing profile is no longer supplied. - Args: home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``. @@ -57,6 +51,15 @@ Args: to testnet. endpoint: Node API origin for a NEW profile. +Raises: + aleo.keystore.KeystoreError: The signing key cannot be resolved. + Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs + to another address than the profile's; ``PASSWORD_REQUIRED`` + when the account is encrypted and nothing supplies its + password; ``ACCOUNT_NOT_FOUND`` when no source has the key of + an existing profile, such as a key variable that is not set + on this run. + ### `onboard(self, referral_code: 'Optional[str]' = None) -> 'OnboardReport'` Register this profile end to end — safe to re-run any time. diff --git a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md index 7a119be4..f57704a3 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md +++ b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md @@ -32,7 +32,7 @@ credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run The signer is the profile's Aleo account, found through the account keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in -``~/.aleo/accounts`` that the profile names. A fresh profile adopts +``~/.aleo/accounts`` that the profile names. A fresh profile uses that account, or creates one and stores it there; the profile itself holds no private key, and a key from the environment is never written to disk. To create the account encrypted, in the macOS Keychain or @@ -44,12 +44,6 @@ 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. -Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key -cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address -than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account -with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an -existing profile is no longer supplied. - Args: home: Profile directory; defaults to ``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``. @@ -57,6 +51,15 @@ Args: to testnet. endpoint: Node API origin for a NEW profile. +Raises: + aleo.keystore.KeystoreError: The signing key cannot be resolved. + Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs + to another address than the profile's; ``PASSWORD_REQUIRED`` + when the account is encrypted and nothing supplies its + password; ``ACCOUNT_NOT_FOUND`` when no source has the key of + an existing profile, such as a key variable that is not set + on this run. + ### `onboard(self, referral_code: 'Optional[str]' = None) -> 'OnboardReport'` Register this profile end to end — safe to re-run any time. diff --git a/shield-swap-sdk/python/aleo_shield_swap/client.py b/shield-swap-sdk/python/aleo_shield_swap/client.py index 33f092de..a0f75f0d 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/client.py +++ b/shield-swap-sdk/python/aleo_shield_swap/client.py @@ -173,7 +173,7 @@ def from_profile(cls, home: Any = None, *, The signer is the profile's Aleo account, found through the account keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in - ``~/.aleo/accounts`` that the profile names. A fresh profile adopts + ``~/.aleo/accounts`` that the profile names. A fresh profile uses that account, or creates one and stores it there; the profile itself holds no private key, and a key from the environment is never written to disk. To create the account encrypted, in the macOS Keychain or @@ -185,18 +185,21 @@ def from_profile(cls, home: Any = None, *, keys and blinded identities are network-scoped and would not transfer. Give each network its own home directory. - Raises ``aleo.keystore.KeystoreError`` (read ``code``) when the key - cannot be resolved: ``ADDRESS_MISMATCH`` for a key of another address - than the profile's, ``PASSWORD_REQUIRED`` for an encrypted account - with no password source, ``ACCOUNT_NOT_FOUND`` when the key of an - existing profile is no longer supplied. - 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. + + Raises: + aleo.keystore.KeystoreError: The signing key cannot be resolved. + Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs + to another address than the profile's; ``PASSWORD_REQUIRED`` + when the account is encrypted and nothing supplies its + password; ``ACCOUNT_NOT_FOUND`` when no source has the key of + an existing profile, such as a key variable that is not set + on this run. """ from aleo import Aleo, HTTPProvider diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index 5fbb24c5..460e4ae1 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -1,12 +1,12 @@ -"""On-disk participant profile: account, credentials and journal location. +"""Bind a participant's home directory to one Aleo account. One profile per home directory (``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``). ``profile.json`` records which Aleo account the profile trades with: its -address and the name of its account file. The private key itself lives in the -Aleo account keystore (``aleo.keystore``, by default -``~/.aleo/accounts/.json``), which every Aleo tool reads, so an account -set up once serves them all. Credentials (JWT, delegated-proving keys) are -stored separately so they can be refreshed without touching the account. +address and the name of its account file. The private key is held by the Aleo +account keystore (``aleo.keystore``, by default +``~/.aleo/accounts/.json``). Every Aleo tool reads that keystore, so an +account set up once serves them all. Credentials (JWT, delegated-proving keys) +are stored separately so they can be refreshed without touching the account. """ from __future__ import annotations @@ -23,8 +23,8 @@ _log = logging.getLogger(__name__) -# Profile files already reported as still holding their key, so the notice is -# given once per process however many Profile objects load the file. +# Profile files already reported as holding their own key. The notice is given +# once per process, however many Profile objects load the file. _legacy_notices: set[str] = set() _legacy_notices_lock = threading.Lock() @@ -39,16 +39,19 @@ def _write_private(path: Path, payload: dict[str, Any]) -> None: def _selected_account_name(account: Optional[str]) -> str: - """The account name a lookup uses when the profile records none. + """Return the account name a lookup selects when the profile records none. - The *account* argument, then ``ALEO_ACCOUNT`` (an empty value counts as - unset), then ``default``: the order the account keystore applies itself. + Applies the account keystore's own order: the *account* argument, then + ``ALEO_ACCOUNT`` (an empty value counts as unset), then ``default``. """ return account if account is not None else (os.environ.get("ALEO_ACCOUNT") or "default") def _report_legacy_key(path: Path, address: str) -> None: - """Log, once per process and profile file, that the file still holds the key.""" + """Log, once per process and profile file, that the file holds the key itself. + + The warning names the command that copies the key into an account file. + """ with _legacy_notices_lock: if str(path) in _legacy_notices: return @@ -150,8 +153,8 @@ def load_or_create(cls, home: "Path | str | None" = None, *, *create*, *storage* and *save_password* apply only when creating. Its key is looked up on the first read of :attr:`private_key`, using *account*, *accounts_dir* and *password* as given here. A profile - written by an earlier release, with the key still in ``profile.json``, - keeps working unchanged. + whose ``profile.json`` holds a ``private_key`` keeps working: that key + is used when no other source supplies one. Reads the environment and the account file. Creating also writes the account file and the profile, and for ``"keychain"`` or @@ -164,11 +167,14 @@ def load_or_create(cls, home: "Path | str | None" = None, *, endpoint: API endpoint to record on a NEW profile. create: Whether to create and store an account when a NEW profile finds none. Defaults to True. - storage: How the keystore holds a newly created key: - ``"plaintext"`` (the default, a file only its owner can read), - ``"keychain"`` (the macOS login keychain) or ``"encrypted"`` - (under a password, on every system). ``"none"`` is rejected, - because nothing would hold the new key once the process exits. + storage: Where the keystore holds a newly created key. + ``"plaintext"`` (the default) writes it to a file only its + owner can read, so an unattended process starts without a + password. ``"keychain"`` holds it in the macOS login + keychain. ``"encrypted"`` holds it under a password on every + system, and each later run needs that password. ``"none"`` + is rejected, because nothing would hold the new key once the + process exits. account: Account name in the keystore. Defaults to ``ALEO_ACCOUNT``, then the name the profile records, then ``default``. @@ -260,10 +266,10 @@ def private_key(self) -> str: object: from ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise from the account file named by the *account* argument of :meth:`load_or_create`, then ``ALEO_ACCOUNT``, then the name the - profile records, then ``default``. A profile written by an earlier - release supplies the key still stored in ``profile.json`` when no - other source has one, and logs once how to move it. Whichever source - supplies the key, it must belong to :attr:`address`. + profile records, then ``default``. A ``private_key`` held in + ``profile.json`` is used when no other source has one, and a warning + is logged once with the command that moves it into an account file. + Whichever source supplies the key, it must belong to :attr:`address`. The first read may run the macOS ``security`` tool or, for an encrypted account, stretch a password (about 200 ms) and ask for it @@ -299,7 +305,7 @@ def _resolve_private_key(self) -> str: name = self._data.get("account") loaded = keystore.load( name=name, dir=self._accounts_dir, - # Profiles written by earlier releases keep the key in the file. + # A profile file may hold the key itself; it is the last source. legacy_key=self._data.get("private_key") or None, expected_address=self.address, password=self._password) diff --git a/shield-swap-sdk/tests/conftest.py b/shield-swap-sdk/tests/conftest.py index 7958f79e..50b58cb2 100644 --- a/shield-swap-sdk/tests/conftest.py +++ b/shield-swap-sdk/tests/conftest.py @@ -31,7 +31,7 @@ class FakeKeychain: """An in-memory stand-in for the macOS ``security`` tool. - Understands the three invocations the account keystore makes (add, find + Accepts the three invocations the account keystore makes (add, find and delete a generic password), so Keychain storage can be exercised without touching the login keychain of the machine running the tests. """ @@ -56,7 +56,7 @@ def run(self, args: Sequence[str], stdin: Optional[str] = None) -> Tuple[Optiona class AccountSandbox: - """The replaced surroundings of one test. + """Hold the stand-ins one test runs against in place of the developer's files. Attributes: home: Stand-in home directory. The default accounts directory and the diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index f0e52101..e67c4151 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -29,7 +29,7 @@ def new_account() -> SimpleNamespace: - """A random account as an address and private-key pair of strings.""" + """Return a random account as an address and private-key pair of strings.""" key = testnet.PrivateKey.random() return SimpleNamespace(address=str(key.address), private_key=str(key)) @@ -41,7 +41,7 @@ def same_secret(actual: object, expected: object) -> None: def failure(call: Callable[[], Any]) -> KeystoreError: - """The keystore error a call fails with.""" + """Return the keystore error a call fails with.""" try: call() except KeystoreError as error: @@ -58,7 +58,7 @@ def files_under(*roots: Path) -> list[Path]: def assert_key_on_no_disk(private_key: str, *roots: Path) -> None: - """No file under *roots* contains the key.""" + """Assert that no file under *roots* contains the key.""" for path in files_under(*roots): if private_key.encode() in path.read_bytes(): raise AssertionError(f"{path} contains a private key") @@ -69,7 +69,7 @@ def saved_profile(home: Path) -> dict[str, Any]: def write_legacy_profile(home: Path, account: SimpleNamespace, **extra: Any) -> Path: - """A profile as earlier releases wrote it: the key inside ``profile.json``.""" + """Write a profile whose ``profile.json`` holds the private key itself.""" home.mkdir(parents=True, exist_ok=True) path = home / "profile.json" data = {"address": account.address, "private_key": account.private_key, @@ -81,7 +81,7 @@ def write_legacy_profile(home: Path, account: SimpleNamespace, **extra: Any) -> @pytest.fixture(autouse=True) def fresh_legacy_notices(monkeypatch): - """The legacy-key notice is given once per process; start each test unnotified.""" + """Clear the once-per-process record of legacy-key notices before each test.""" monkeypatch.setattr(profile_module, "_legacy_notices", set()) @@ -102,7 +102,7 @@ def counted(**kwargs: Any): # ── The test surroundings themselves ───────────────────────────────────────── def test_tests_run_against_a_stand_in_home(account_sandbox, tmp_path): - """Guards the guard: nothing here may resolve to the developer's own files.""" + """Check that nothing here resolves to the developer's own files.""" import os assert Path.home() == account_sandbox.home @@ -708,7 +708,7 @@ def test_from_profile_reports_a_locked_account(tmp_path, monkeypatch): assert not (tmp_path / "home").exists() -# ── Homes, credentials and the journal are unchanged ───────────────────────── +# ── Homes, credentials and the journal ─────────────────────────────────────── def test_env_home_override(tmp_path, monkeypatch): monkeypatch.setenv("SHIELD_SWAP_HOME", str(tmp_path / "envhome")) From b96c8ed50457b281ff32459ebb5d867f06c28479 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:07:57 -0500 Subject: [PATCH 3/9] docs(shield-swap): explain accounts and key protection from the caller's perspective --- shield-swap-sdk/AGENTS.md | 103 ++++--- shield-swap-sdk/README.md | 160 ++++++---- shield-swap-sdk/codegen/gen_context.py | 33 ++- shield-swap-sdk/examples/first-swap/README.md | 25 +- shield-swap-sdk/examples/first-swap/swap.py | 4 +- shield-swap-sdk/pyproject.toml | 2 +- .../python/aleo_shield_swap/AGENTS.md | 103 ++++--- .../python/aleo_shield_swap/__init__.py | 7 +- .../python/aleo_shield_swap/client.py | 76 +++-- .../python/aleo_shield_swap/mcp.py | 62 ++-- .../python/aleo_shield_swap/profile.py | 278 +++++++++--------- shield-swap-sdk/tests/conftest.py | 37 +-- .../integration/test_agent_lifecycle_live.py | 6 +- .../tests/integration/test_swap_lifecycle.py | 2 +- .../tests/test_first_swap_account.py | 4 +- shield-swap-sdk/tests/test_gen_context.py | 18 +- shield-swap-sdk/tests/test_package.py | 4 +- shield-swap-sdk/tests/test_profile.py | 70 +++-- 18 files changed, 533 insertions(+), 461 deletions(-) diff --git a/shield-swap-sdk/AGENTS.md b/shield-swap-sdk/AGENTS.md index f57704a3..a645f264 100644 --- a/shield-swap-sdk/AGENTS.md +++ b/shield-swap-sdk/AGENTS.md @@ -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() # account from the Aleo keystore, created on first use +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, @@ -23,42 +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`. -The signer is the profile's Aleo account, found through the account -keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or -``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in -``~/.aleo/accounts`` that the profile names. A fresh profile uses -that account, or creates one and stores it there; the profile itself -holds no private key, and a key from the environment is never written -to disk. To create the account encrypted, in the macOS Keychain or -under another name, call :meth:`Profile.load_or_create` on the same -*home* first. +For a new account, use macOS Keychain or password encryption to +protect the private key. Set this up before building the client:: -*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. + 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 signing key cannot be resolved. - Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs - to another address than the profile's; ``PASSWORD_REQUIRED`` - when the account is encrypted and nothing supplies its - password; ``ACCOUNT_NOT_FOUND`` when no source has the key of - an existing profile, such as a key variable that is not set - on this run. + 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'` @@ -118,17 +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, in their own terminal, before the profile is - first created: `python -m aleo.keystore import` stores it once (hidden - prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or - `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from - the environment is never written to disk. The key lives in the Aleo - account keystore (`~/.aleo/accounts/`), not in the profile; never run - `python -m aleo.keystore export` or read an account file, both reveal it. +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=)`) @@ -207,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 in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); 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. | diff --git a/shield-swap-sdk/README.md b/shield-swap-sdk/README.md index 663e8f34..b6a79bba 100644 --- a/shield-swap-sdk/README.md +++ b/shield-swap-sdk/README.md @@ -72,76 +72,118 @@ 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`. -## Profiles and the account key - -`ShieldSwap.from_profile()` and `Profile.load_or_create()` keep a trader's -state between runs in a profile home (`~/.shield-swap`, `SHIELD_SWAP_HOME`, -or the `home` argument): API credentials, the swap journal, and -`profile.json`, which records the account's address, its account name, the -network and the endpoint. - -The private key is not in the profile. It is found through the Aleo SDK's -account keystore ([`aleo.keystore`](../sdk/Readme.md#store-an-account--aleokeystore)), -which the other Aleo tools read as well, so an account set up once serves all -of them: - -1. `ALEO_PRIVATE_KEY`, or the text file named by `ALEO_PRIVATE_KEY_FILE` - (`SHIELD_SWAP_PRIVATE_KEY` and `SHIELD_SWAP_PRIVATE_KEY_FILE` are aliases). - A key supplied this way is used for the process and never written to disk, - so it has to be supplied on every run. -2. The account file `~/.aleo/accounts/.json`. The name comes from the - `account` argument, then `ALEO_ACCOUNT`, then the name recorded in the - profile, then `default`. - -A new profile adopts the account those sources supply. When there is none it -creates an account and stores it in the keystore; `create=False` raises -instead. Two profile homes that select the same account name therefore share -one account: give a second address its own home and its own `account` name. -Whichever source supplies the key later, it must belong to the -address the profile records, so a stale variable or the wrong account name is -an error naming both addresses instead of a trade from another account. +## 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. + +### 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 -# First run: adopt the stored account, or create one and store it. -profile = Profile.load_or_create() +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: -# Or choose how a newly created key is held, then build the client. An -# encrypted account takes its password from ALEO_ACCOUNT_PASSWORD or asks for -# it twice on the terminal. -Profile.load_or_create("~/.shield-swap-main", network="mainnet", account="mainnet", - storage="encrypted", save_password=True) -dex = ShieldSwap.from_profile("~/.shield-swap-main") +```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 ``` -`storage` applies when an account is created: `"plaintext"` (the default) is -a file only its owner can read; `"keychain"` keeps the key in the macOS login -keychain; `"encrypted"` encrypts it under a password, which later runs take -from the `password` argument, `ALEO_ACCOUNT_PASSWORD`, the macOS Keychain -(`save_password=True`, macOS only) or a hidden prompt on a terminal. Keychain and -encrypted storage protect a copied or backed-up file; they do not stop -another process running as the same user. An unattended job with an encrypted -account needs the variable or the saved password, because it cannot answer a -prompt. - -`profile.private_key` looks the key up on first use and raises -`aleo.keystore.KeystoreError` when it cannot: read `error.code` -(`PASSWORD_REQUIRED`, `ADDRESS_MISMATCH`, `ACCOUNT_NOT_FOUND`, …). -`accounts_dir` (or `ALEO_ACCOUNTS_DIR`) points at another accounts directory; -the profile does not record it, so pass it on every run. - -A profile written by an earlier release keeps its key in `profile.json` and -works unchanged. The first read of its key logs one warning on the -`aleo_shield_swap.profile` logger with the command that moves the key: +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/.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 --remove-legacy-key +python -m aleo.keystore migrate --from ~/.shield-swap/profile.json --storage encrypted --remove-legacy-key ``` -Without `--remove-legacy-key` the command copies the key and leaves the -plaintext copy in `profile.json`. Earlier releases cannot read a profile that -no longer holds the 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 diff --git a/shield-swap-sdk/codegen/gen_context.py b/shield-swap-sdk/codegen/gen_context.py index e9ee0da5..8d045ca9 100644 --- a/shield-swap-sdk/codegen/gen_context.py +++ b/shield-swap-sdk/codegen/gen_context.py @@ -43,9 +43,10 @@ QUICKSTART = """\ ```python -from aleo_shield_swap import ShieldSwap +from aleo_shield_swap import Profile, ShieldSwap -dex = ShieldSwap.from_profile() # account from the Aleo keystore, created on first use +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, @@ -58,17 +59,19 @@ ### 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, in their own terminal, before the profile is - first created: `python -m aleo.keystore import` stores it once (hidden - prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or - `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from - the environment is never written to disk. The key lives in the Aleo - account keystore (`~/.aleo/accounts/`), not in the profile; never run - `python -m aleo.keystore export` or read an account file, both reveal it. +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=)`) @@ -147,7 +150,7 @@ | Building | Stack | Keys live | | --- | --- | --- | -| Bot / server / CLI / notebook | `aleo-sdk` facade + `shield-swap-sdk` (this package) | A local private key in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); 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. | @@ -210,7 +213,7 @@ def render() -> str: "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", "", QUICKSTART, "", diff --git a/shield-swap-sdk/examples/first-swap/README.md b/shield-swap-sdk/examples/first-swap/README.md index 360a9eb0..9d5cace5 100644 --- a/shield-swap-sdk/examples/first-swap/README.md +++ b/shield-swap-sdk/examples/first-swap/README.md @@ -19,13 +19,26 @@ An installed release that contains the example also supports: python -m aleo_shield_swap.examples.first_swap.swap ``` -## 1. Create an account +## 1. Choose the account to trade with -Start with an existing testnet private key or let the SDK create and retain -one. `Profile.load_or_create` stores a new account in the Aleo account -keystore (`~/.aleo/accounts/default.json`), where the other Aleo tools find it -too, and records its address in `~/.shield-swap/profile.json`. Later runs -reuse that account. +Use an existing testnet account to keep its address and funds. Before running +the example, import its key from a terminal: + +```sh +python -m aleo.keystore import --storage encrypted +``` + +For a new account, run `python -m aleo.keystore create --storage encrypted` +instead. Both commands ask for a password without displaying it. On macOS, +`--storage keychain` keeps the key in Keychain instead of encrypting it in a +file. These are the recommended choices: the default, plaintext, leaves the +private key readable to anyone with access to the account file. + +The example reuses this account on later runs. With no account set up, it +creates one using plaintext storage in `~/.aleo/accounts/default.json` and +records its address in `~/.shield-swap/profile.json`. An encrypted account +needs its password at startup; unattended runs need `ALEO_ACCOUNT_PASSWORD` +or a password saved in macOS Keychain. ```python import os diff --git a/shield-swap-sdk/examples/first-swap/swap.py b/shield-swap-sdk/examples/first-swap/swap.py index 2577abb9..23e693a6 100644 --- a/shield-swap-sdk/examples/first-swap/swap.py +++ b/shield-swap-sdk/examples/first-swap/swap.py @@ -17,8 +17,8 @@ # Use a configured private key or create a new key. key = os.environ.get("SHIELD_SWAP_PRIVATE_KEY") if not key: - # Load the profile's account from the Aleo account keystore, or create - # an account and store it there on the first run. + # Reuse the account on later runs so its funds remain available. + # With no saved account, this creates one using plaintext storage. profile = Profile.load_or_create(network="testnet") if profile.network != "testnet": raise RuntimeError("This example requires a testnet profile") diff --git a/shield-swap-sdk/pyproject.toml b/shield-swap-sdk/pyproject.toml index e0c24ee9..7a7235a9 100644 --- a/shield-swap-sdk/pyproject.toml +++ b/shield-swap-sdk/pyproject.toml @@ -4,7 +4,7 @@ version = "0.9.0" description = "Python SDK for the shield swap AMM Dex on Aleo" readme = "README.md" requires-python = ">=3.10" -dependencies = ["aleo-sdk>=0.9.0", "requests>=2"] # 0.9.0: aleo.keystore (account keystore) +dependencies = ["aleo-sdk>=0.9.0", "requests>=2"] # Profiles require aleo.keystore. [project.optional-dependencies] async = ["httpx>=0.27"] diff --git a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md index f57704a3..a645f264 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md +++ b/shield-swap-sdk/python/aleo_shield_swap/AGENTS.md @@ -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() # account from the Aleo keystore, created on first use +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, @@ -23,42 +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`. -The signer is the profile's Aleo account, found through the account -keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or -``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in -``~/.aleo/accounts`` that the profile names. A fresh profile uses -that account, or creates one and stores it there; the profile itself -holds no private key, and a key from the environment is never written -to disk. To create the account encrypted, in the macOS Keychain or -under another name, call :meth:`Profile.load_or_create` on the same -*home* first. +For a new account, use macOS Keychain or password encryption to +protect the private key. Set this up before building the client:: -*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. + 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 signing key cannot be resolved. - Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs - to another address than the profile's; ``PASSWORD_REQUIRED`` - when the account is encrypted and nothing supplies its - password; ``ACCOUNT_NOT_FOUND`` when no source has the key of - an existing profile, such as a key variable that is not set - on this run. + 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'` @@ -118,17 +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, in their own terminal, before the profile is - first created: `python -m aleo.keystore import` stores it once (hidden - prompt, or `--key-file `), or `export ALEO_PRIVATE_KEY=...` (or - `ALEO_PRIVATE_KEY_FILE=path`) supplies it for each session — a key from - the environment is never written to disk. The key lives in the Aleo - account keystore (`~/.aleo/accounts/`), not in the profile; never run - `python -m aleo.keystore export` or read an account file, both reveal it. +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=)`) @@ -207,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 in the Aleo account keystore (`ShieldSwap.from_profile()` finds it, or creates and stores one on first use); 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. | diff --git a/shield-swap-sdk/python/aleo_shield_swap/__init__.py b/shield-swap-sdk/python/aleo_shield_swap/__init__.py index bd2cbb43..9996cada 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/__init__.py +++ b/shield-swap-sdk/python/aleo_shield_swap/__init__.py @@ -18,12 +18,9 @@ def _require_aleo_sdk() -> None: - """Fail at import, naming the fix, when the installed aleo-sdk predates ``aleo.keystore``. + """Report the required SDK upgrade before a caller tries to load an account. - The account keystore comes from ``aleo.keystore``, which first shipped in aleo-sdk 0.9.0 - (record management, from ``aleo.inventory``, arrived in 0.8.0, and freeze-list proofs, - from ``aleo.compliance``, in 0.7.0). An older install would otherwise fail the first time - a profile looks for its account, with a bare ``ModuleNotFoundError``. + Profiles need ``aleo.keystore``, available in aleo-sdk 0.9.0 and later. """ try: import aleo.keystore # noqa: F401 diff --git a/shield-swap-sdk/python/aleo_shield_swap/client.py b/shield-swap-sdk/python/aleo_shield_swap/client.py index a0f75f0d..829381b2 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/client.py +++ b/shield-swap-sdk/python/aleo_shield_swap/client.py @@ -164,42 +164,54 @@ def __repr__(self) -> str: def from_profile(cls, home: Any = None, *, network: Optional[str] = None, endpoint: Optional[str] = None) -> "ShieldSwap": - """The client for the local participant profile (created on first use). - - Wires endpoint, network, signer, and (when present) delegated-proving - credentials from ``$SHIELD_SWAP_HOME``/``~/.shield-swap``. Run - ``onboard()`` next on a fresh profile. - - The signer is the profile's Aleo account, found through the account - keystore (``aleo.keystore``): a key in ``ALEO_PRIVATE_KEY`` or - ``ALEO_PRIVATE_KEY_FILE`` when set, otherwise the account file in - ``~/.aleo/accounts`` that the profile names. A fresh profile uses - that account, or creates one and stores it there; the profile itself - holds no private key, and a key from the environment is never written - to disk. To create the account encrypted, in the macOS Keychain or - under another name, call :meth:`Profile.load_or_create` on the same - *home* first. - - *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. + """Continue trading with the same account, credentials, and swap journal. + + 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`. + + 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 signing key cannot be resolved. - Read ``code``: ``ADDRESS_MISMATCH`` when the key found belongs - to another address than the profile's; ``PASSWORD_REQUIRED`` - when the account is encrypted and nothing supplies its - password; ``ACCOUNT_NOT_FOUND`` when no source has the key of - an existing profile, such as a key variable that is not set - on this run. + 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. """ from aleo import Aleo, HTTPProvider diff --git a/shield-swap-sdk/python/aleo_shield_swap/mcp.py b/shield-swap-sdk/python/aleo_shield_swap/mcp.py index 24a4fc60..91bc492f 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/mcp.py +++ b/shield-swap-sdk/python/aleo_shield_swap/mcp.py @@ -1,26 +1,34 @@ -"""MCP server exposing shield_swap as tools (the ``[mcp]`` extra). +"""Use Shield Swap from an MCP client. -Run: ``python -m aleo_shield_swap.mcp`` +Install ``shield-swap-sdk[mcp]`` and run +``python -m aleo_shield_swap.mcp``. By default, the server uses the local +profile to retain the account, API credentials, and unfinished swaps +between sessions. -Uses the low-level ``mcp.server.Server`` (not FastMCP) so each tool -advertises the exact JSON schema from :func:`~aleo_shield_swap.agent -.shield_swap_tools` — FastMCP infers schemas from handler signatures, which -would collapse every tool to one opaque ``args`` object. Tools run against -the synchronous :class:`~aleo_shield_swap.client.ShieldSwap` (its full method -surface) in a worker thread, keeping the event loop free. +Set up the account before starting the server. Import an existing account +to keep its address and funds, or create one for a separate address. +Use macOS Keychain or encrypted storage to protect the private key; see +:meth:`~aleo_shield_swap.profile.Profile.load_or_create`. Without setup, +the first run can create an account with its key stored as plaintext. + +An encrypted account needs ``ALEO_ACCOUNT_PASSWORD`` or a password saved +in the macOS Keychain: a server connected over stdio cannot answer a +password prompt. Environment: - ALEO_ENDPOINT API service root (default ``https://edge.provable.com/api``, no credentials — - the provider derives ``/v2`` reads, ``/prove``, and - ``/scanner`` from it) - ALEO_PRIVATE_KEY Explicit signer (overrides the profile); without it - the server binds ShieldSwap.from_profile() — the - ~/.shield-swap journal and credentials, signing with - the profile's account from the Aleo account keystore - (~/.aleo/accounts) - ALEO_NETWORK ``testnet`` (default) or ``mainnet`` + SHIELD_SWAP_HOME Profile directory; defaults to ``~/.shield-swap``. + ALEO_ACCOUNT Account name; defaults to the profile's saved name, + then ``default``. + ALEO_ACCOUNTS_DIR Account directory; defaults to ``~/.aleo/accounts``. + ALEO_PRIVATE_KEY Use this key directly, without the profile's journal + or credentials. Supply it again on each server start. + ALEO_ENDPOINT API service root for a direct-key client; defaults to + ``https://edge.provable.com/api``. + ALEO_NETWORK ``testnet`` (default) or ``mainnet`` for a direct-key + client. A profile keeps its recorded network. ALEO_E2E_API_KEY / ALEO_E2E_CONSUMER_ID - Delegated-proving + hosted-scanner credentials + Optional service credentials for a direct-key client. + A profile uses its saved credentials instead. """ from __future__ import annotations @@ -86,21 +94,17 @@ def _build_dex() -> Any: if pk: aleo.default_account = aleo.account.from_private_key(pk) return ShieldSwap(aleo) - # No explicit key: bind the local participant profile (created on first - # use), so MCP agents get persistence — journal, counters, credentials. - # Its account comes from the Aleo account keystore. + # Keep pending swaps and credentials available when the MCP client restarts. return ShieldSwap.from_profile() def main() -> None: - """Serve the shield_swap MCP tools over stdio until the client disconnects. - - Builds a DEX client first, which binds a key from ``ALEO_PRIVATE_KEY`` or - else creates/loads the local participant profile on disk and signs with - its account from the Aleo account keystore. An encrypted account needs - ``ALEO_ACCOUNT_PASSWORD`` or a password saved in the macOS Keychain here, - because a server on stdio has no terminal to ask on. Blocks for the - lifetime of the server; requires the ``[mcp]`` extra. + """Serve Shield Swap tools until the MCP client disconnects. + + Requires ``shield-swap-sdk[mcp]``. Prepare the account and any password + before starting; see the module's setup instructions. Without + ``ALEO_PRIVATE_KEY``, the server uses the saved profile and journal. + Setting that variable starts a client without profile persistence. """ import anyio from mcp.server.stdio import stdio_server diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index 460e4ae1..17e7aad8 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -1,12 +1,13 @@ -"""Bind a participant's home directory to one Aleo account. - -One profile per home directory (``$SHIELD_SWAP_HOME`` or ``~/.shield-swap``). -``profile.json`` records which Aleo account the profile trades with: its -address and the name of its account file. The private key is held by the Aleo -account keystore (``aleo.keystore``, by default -``~/.aleo/accounts/.json``). Every Aleo tool reads that keystore, so an -account set up once serves them all. Credentials (JWT, delegated-proving keys) -are stored separately so they can be refreshed without touching the account. +"""Keep a trading account and its saved work available between runs. + +A profile ties one Aleo address to a directory containing API credentials +and a swap journal. Reuse that directory to continue trading and collect +pending swaps. The default is ``SHIELD_SWAP_HOME``, then ``~/.shield-swap``. + +New profiles store the address and account name in ``profile.json``. The +private key is loaded through ``aleo.keystore`` or supplied through the +environment. Use macOS Keychain or encrypted account storage to protect a +saved key; see :meth:`Profile.load_or_create`. """ from __future__ import annotations @@ -23,8 +24,7 @@ _log = logging.getLogger(__name__) -# Profile files already reported as holding their own key. The notice is given -# once per process, however many Profile objects load the file. +# Avoid repeating the migration warning when several objects load one profile. _legacy_notices: set[str] = set() _legacy_notices_lock = threading.Lock() @@ -39,18 +39,18 @@ def _write_private(path: Path, payload: dict[str, Any]) -> None: def _selected_account_name(account: Optional[str]) -> str: - """Return the account name a lookup selects when the profile records none. + """Choose a name to record when no account file supplies one. - Applies the account keystore's own order: the *account* argument, then - ``ALEO_ACCOUNT`` (an empty value counts as unset), then ``default``. + Use the same defaults as the keystore: ``account``, then a nonempty + ``ALEO_ACCOUNT``, then ``default``. """ return account if account is not None else (os.environ.get("ALEO_ACCOUNT") or "default") def _report_legacy_key(path: Path, address: str) -> None: - """Log, once per process and profile file, that the file holds the key itself. + """Point callers to the migration command for a key still in profile.json. - The warning names the command that copies the key into an account file. + Report each file once per process without including the key. """ with _legacy_notices_lock: if str(path) in _legacy_notices: @@ -64,45 +64,42 @@ def _report_legacy_key(path: Path, address: str) -> None: class Profile: - """A participant's persistent identity and credentials. + """Reuse an account and its trading history across sessions. - Holds exactly one Aleo address, fixed when the profile is created and - reused every session after. For several addresses, create a profile per - address — each needs its own home directory (``SHIELD_SWAP_HOME``, or - *home* on :meth:`load_or_create`), since the journal and credentials are - per-profile too — and give each its own account name. + Load the same profile on each run to keep its address, API credentials, + and swap journal together. A profile belongs to one address and one + network; give a separate account or network its own home directory. - Load with :meth:`load_or_create`. The same call serves the first run and - every later one, so callers never branch on whether a profile exists:: + Use :meth:`load_or_create` to open the profile. If an account already + exists, the profile uses it. Otherwise it generates a key. For a new + key, choose password encryption or macOS Keychain storage:: from aleo_shield_swap import Profile - # First run: uses the stored Aleo account, or creates and stores one. - profile = Profile.load_or_create() - print(profile.address) # aleo1… - - # Every run after: the same call returns that account, unchanged. - assert Profile.load_or_create().address == profile.address + profile = Profile.load_or_create(storage="encrypted") + address = profile.address - # A second address needs its own home and its own account name. - other = Profile.load_or_create("~/.shield-swap-alt", account="alt") + The first run asks for an encryption password unless one was supplied. + Later runs need that password to unlock the key. On macOS, + ``storage="keychain"`` keeps the key in Keychain instead of the account + file. The default, ``"plaintext"``, leaves the key readable to anyone + with access to the file. Passing ``storage`` does not convert an + existing account; use ``python -m aleo.keystore protect`` for that. - The private key is not in the profile. It is found through the Aleo - account keystore: the ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` - variables for a key supplied per run, otherwise the account file the - profile names. A key from the environment is used for the process and - never written to disk. Whichever source supplies it, the key must belong - to the profile's address. + A second home directory alone does not create a separate account: + profiles selecting the same account name share its key. To trade from + another address, use a separate home and ``account`` name, and clear + any key variables that still select the first account. """ def __init__(self, home: Path, data: dict[str, Any]) -> None: self.home = home self._data = data - # How to find the key of an existing profile, as given to load_or_create(). + # Retain these options so inspecting a profile does not require unlocking it. self._account: Optional[str] = None self._accounts_dir: "Path | str | None" = None self._password: Optional[str] = None - # The key, once resolved; one lookup serves the object's lifetime. + # Reuse the unlocked key for this object instead of prompting on every read. self._private_key: Optional[str] = None self._key_lock = threading.Lock() @@ -133,86 +130,87 @@ def load_or_create(cls, home: "Path | str | None" = None, *, accounts_dir: "Path | str | None" = None, password: Optional[str] = None, save_password: bool = False) -> "Profile": - """Load the profile at *home*, binding one to an Aleo account if absent. - - A new profile takes the account the Aleo account keystore resolves: a - key in ``ALEO_PRIVATE_KEY`` or the file named by - ``ALEO_PRIVATE_KEY_FILE`` (``SHIELD_SWAP_PRIVATE_KEY`` and - ``SHIELD_SWAP_PRIVATE_KEY_FILE`` are aliases), otherwise the account - file selected by *account*. A user with an existing account supplies - it one of these ways rather than pasting a key into a chat. When - neither exists, a new account is created and stored in the keystore - with the chosen *storage*; pass ``create=False`` to raise instead. A - key from the environment is used for this process and never written - to disk, so it has to be supplied again on every later run. - - ``profile.json`` then records the address, the account name, the - network and the endpoint, at mode 600. It holds no private key. - - An existing profile is returned as recorded: *network*, *endpoint*, - *create*, *storage* and *save_password* apply only when creating. Its - key is looked up on the first read of :attr:`private_key`, using - *account*, *accounts_dir* and *password* as given here. A profile - whose ``profile.json`` holds a ``private_key`` keeps working: that key - is used when no other source supplies one. - - Reads the environment and the account file. Creating also writes the - account file and the profile, and for ``"keychain"`` or - ``"encrypted"`` storage writes the macOS Keychain or asks for a - password on an attached terminal. Does not contact a network. + """Open a trading profile, creating one if this is its first run. + + To keep an existing address and its funds, import its key with + ``python -m aleo.keystore import --storage encrypted`` first, then + load the profile with ``create=False``. On macOS, ``--storage keychain`` + keeps the key in Keychain. Import keys in a terminal, never in a chat. + ``create=False`` permits a new profile but requires an existing key. + + To start with a separate address, choose an unused account name and + profile home. Use ``storage="keychain"`` on macOS or + ``storage="encrypted"`` to protect a newly generated key. The default + is plaintext, which leaves the private key readable in the account + file. ``storage`` applies only when generating a key; it does not + change an existing account. ``python -m aleo.keystore protect`` can + change storage while keeping the address and funds. + + The profile records its address, account name, network, and endpoint + in ``profile.json``. Creating it does not contact the network or move + funds. An existing profile keeps its recorded settings and can be + opened without a password; its key is unlocked on the first read of + :attr:`private_key`. + + Keys supplied through ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` + take precedence over saved keys and are never copied to disk. Supply + the key again on each 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, if present, the selected account file. Args: - home: Profile directory; defaults to :meth:`default_home`. - network: Network to bind a NEW profile to. - endpoint: API endpoint to record on a NEW profile. - create: Whether to create and store an account when a NEW profile - finds none. Defaults to True. - storage: Where the keystore holds a newly created key. - ``"plaintext"`` (the default) writes it to a file only its - owner can read, so an unattended process starts without a - password. ``"keychain"`` holds it in the macOS login - keychain. ``"encrypted"`` holds it under a password on every - system, and each later run needs that password. ``"none"`` - is rejected, because nothing would hold the new key once the - process exits. - account: Account name in the keystore. Defaults to - ``ALEO_ACCOUNT``, then the name the profile records, then - ``default``. - accounts_dir: Accounts directory. Defaults to - ``ALEO_ACCOUNTS_DIR``, then ``~/.aleo/accounts``. The profile - does not record it; pass it again on later runs. - password: Password of an ``"encrypted"`` account. Defaults to - ``ALEO_ACCOUNT_PASSWORD``, a password saved in the macOS - Keychain, then a hidden prompt on an attached terminal. - save_password: Also save the password of a newly created - ``"encrypted"`` account in the macOS Keychain, so later runs - need no password. Defaults to False. + home: Directory for the profile, credentials, and swap journal. + Defaults to ``SHIELD_SWAP_HOME``, then ``~/.shield-swap``. + network: ``"testnet"`` (default) or ``"mainnet"`` for a new profile. + An existing profile keeps its network; use another home to + trade on a different network. + endpoint: API service root for a new profile. Defaults to + ``https://edge.provable.com/api``; ignored for an existing profile. + create: Generate and save a key if none is found for a new profile. + Defaults to True. Use False to require an existing account. + storage: Protection for a generated key. ``"encrypted"`` encrypts + the key in the account file and requires a password to unlock + it. ``"keychain"`` stores the key in macOS Keychain, outside + the file. ``"plaintext"`` (default) restricts file permissions + but does not encrypt the key or protect a copied file. The + address remains readable in every mode. ``"none"`` is rejected + because the generated key would be lost when the process exits. + account: Name of the saved account. Defaults to ``ALEO_ACCOUNT``, + then the profile's saved name, then ``default``. Use a distinct + name as well as a distinct home for each separate account. + accounts_dir: Directory containing account files. Defaults to + ``ALEO_ACCOUNTS_DIR``, then ``~/.aleo/accounts``. This location + is not saved in the profile; supply it on each run. + password: Password to unlock an encrypted account or protect a new + key. If omitted, uses ``ALEO_ACCOUNT_PASSWORD``, then a password + saved in macOS Keychain, then a hidden terminal prompt. + save_password: Save a new encrypted account's password in macOS + Keychain so later runs can unlock it without a prompt. + Defaults to False; applies only when generating a key. Returns: - The loaded or newly created profile. + The profile for the recorded address. For an existing profile, + opening it does not check whether its key is available; read + :attr:`private_key` when it is needed for signing. Raises: - aleo.keystore.KeystoreError: Read ``code``. For a NEW profile: - ``ACCOUNT_NOT_FOUND`` when no account resolves and *create* is - False; ``UNSUPPORTED_STORAGE`` when an account would be - created with ``"none"`` or an unknown *storage*; - ``EMPTY_KEY_SOURCE``, ``KEY_CONFLICT`` or ``INVALID_KEY`` for - unusable key variables; ``ADDRESS_MISMATCH`` when a key from - the environment belongs to another address than the selected - account file; ``KEY_NOT_STORED`` when that file records an - address only and no key was supplied; ``PASSWORD_REQUIRED`` or - ``WRONG_PASSWORD`` for an encrypted account; - ``KEYCHAIN_UNAVAILABLE`` for ``"keychain"`` outside macOS; - ``INVALID_NAME`` for an unusable *account*. + aleo.keystore.KeystoreError: A new profile cannot open or save its + account. Check ``code``: ``ACCOUNT_NOT_FOUND`` with + ``create=False`` means the account must be imported or supplied; + ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD`` requires a valid + password; ``ADDRESS_MISMATCH`` means the supplied key belongs + to another account. Other codes identify invalid key sources, + names, or unavailable storage. An existing profile reports key + errors when :attr:`private_key` is read. """ - # expanduser: a "~/..." string is otherwise taken literally, creating a - # directory named ~ in the cwd and writing the profile there. + # Treat ~ as the user's home, including paths passed directly from Python. home = Path(home).expanduser() if home is not None else cls.default_home() path = home / _PROFILE if path.exists(): path.chmod(0o600) # heal a pre-existing loose mode profile = cls(home, json.loads(path.read_text())) - # The key is looked up when it is first read, with these options. + # Allow address and credential reads before the account is unlocked. profile._account = account profile._accounts_dir = accounts_dir profile._password = password @@ -223,8 +221,7 @@ def load_or_create(cls, home: "Path | str | None" = None, *, try: loaded = keystore.load(name=account, dir=accounts_dir, password=password) private_key, address = loaded.private_key, loaded.address - # A key from the environment needs no account file; the name - # the lookup selected is recorded all the same. + # Remember the account name even when the key is supplied per run. name = loaded.stored.name if loaded.stored is not None else _selected_account_name(account) except keystore.KeystoreError as error: if error.code != "ACCOUNT_NOT_FOUND" or not create: @@ -237,7 +234,7 @@ def load_or_create(cls, home: "Path | str | None" = None, *, ) from None private_key = str(net.PrivateKey.random()) stored = keystore.save(private_key, name=account, dir=accounts_dir, - storage=cast(Any, storage), # save() rejects an unknown value + storage=cast(Any, storage), # save() validates storage. password=password, save_password=save_password) address, name = stored.address, stored.name home.mkdir(parents=True, exist_ok=True) @@ -257,35 +254,35 @@ def address(self) -> str: @property def private_key(self) -> str: - """The private key of the profile's account. + """Unlock the account's private key for signing. - Whoever holds this controls the account and can decrypt its records — do - not log it, echo it into a conversation, or send it to a service. + The key gives control of the account's funds and can decrypt its + records. Keep it out of logs, conversations, and service requests. - The key is looked up on first use and kept for the lifetime of this - object: from ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` when - set, otherwise from the account file named by the *account* argument - of :meth:`load_or_create`, then ``ALEO_ACCOUNT``, then the name the - profile records, then ``default``. A ``private_key`` held in - ``profile.json`` is used when no other source has one, and a warning - is logged once with the command that moves it into an account file. - Whichever source supplies the key, it must belong to :attr:`address`. + For an existing profile, the first read loads the key and checks + that it belongs to :attr:`address`. An encrypted account may ask + for its password. Later reads reuse the unlocked key for this + object's lifetime, so changes to key variables or files take effect + only after loading another profile object. - The first read may run the macOS ``security`` tool or, for an - encrypted account, stretch a password (about 200 ms) and ask for it - on an attached terminal. + A key in ``ALEO_PRIVATE_KEY`` or ``ALEO_PRIVATE_KEY_FILE`` is used + before the saved account. Account selection follows the ``account`` + argument, ``ALEO_ACCOUNT``, the profile's saved name, then ``default``. + An older profile containing a private key still works when no other + key source or account file exists. Using that key logs a migration + command once per profile file per process; it does not move or delete + the key. Raises: - aleo.keystore.KeystoreError: Read ``code``. ``ADDRESS_MISMATCH`` - when the key found belongs to another address; the message - names both. ``ACCOUNT_NOT_FOUND`` when no source has a key, - such as a profile created from a key in the environment that - is no longer set. ``PASSWORD_REQUIRED`` when the account is - encrypted and no password was passed, set in - ``ALEO_ACCOUNT_PASSWORD``, saved in the Keychain or typed at - a terminal; ``WRONG_PASSWORD`` when it does not unlock the - key. ``EMPTY_KEY_SOURCE`` or ``KEY_CONFLICT`` for key - variables that are empty or disagree. + aleo.keystore.KeystoreError: Check ``code`` to decide what to supply. + ``ACCOUNT_NOT_FOUND`` means the key is missing; + ``KEY_NOT_STORED`` means the account file contains only an + address. Import or supply the original key in either case. + ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD`` means an encrypted + account needs its password. ``ADDRESS_MISMATCH`` means the key + belongs to another address; the message names both addresses. + ``EMPTY_KEY_SOURCE`` or ``KEY_CONFLICT`` identifies empty or + conflicting key variables. """ if self._private_key is None: with self._key_lock: @@ -294,24 +291,23 @@ def private_key(self) -> str: return self._private_key def _resolve_private_key(self) -> str: - """Find the key of an existing profile through the account keystore.""" + """Load a key that matches the saved address before allowing it to sign.""" from aleo import keystore - # The keystore lets its name argument override ALEO_ACCOUNT, so the - # recorded name is passed only when neither the caller nor the - # variable selects an account. + # Passing the saved name would override ALEO_ACCOUNT in keystore.load(). + # Use it only when neither the caller nor the environment selects a name. name = self._account if name is None and not os.environ.get("ALEO_ACCOUNT"): name = self._data.get("account") loaded = keystore.load( name=name, dir=self._accounts_dir, - # A profile file may hold the key itself; it is the last source. + # Keep older profiles usable until their keys are migrated. legacy_key=self._data.get("private_key") or None, expected_address=self.address, password=self._password) if loaded.source == "legacy": _report_legacy_key(self.home / _PROFILE, self.address) - self._password = None # the key is held now; the password is not needed again + self._password = None # Release the password reference after unlocking. return loaded.private_key @property diff --git a/shield-swap-sdk/tests/conftest.py b/shield-swap-sdk/tests/conftest.py index 50b58cb2..1c3b67b7 100644 --- a/shield-swap-sdk/tests/conftest.py +++ b/shield-swap-sdk/tests/conftest.py @@ -14,8 +14,7 @@ import pytest -# Variables a developer's shell could leak into a test: each one selects an -# account, a key, a password or a profile home. +# Clear these variables so tests cannot select a real account or profile. ACCOUNT_VARIABLES = ( "ALEO_PRIVATE_KEY", "ALEO_PRIVATE_KEY_FILE", @@ -29,11 +28,10 @@ class FakeKeychain: - """An in-memory stand-in for the macOS ``security`` tool. + """Test Keychain storage without reading or changing macOS Keychain. - Accepts the three invocations the account keystore makes (add, find - and delete a generic password), so Keychain storage can be exercised - without touching the login keychain of the machine running the tests. + Keep entries in memory and accept the add, find, and delete commands + used by the keystore. """ def __init__(self) -> None: @@ -56,15 +54,13 @@ def run(self, args: Sequence[str], stdin: Optional[str] = None) -> Tuple[Optiona class AccountSandbox: - """Hold the stand-ins one test runs against in place of the developer's files. + """Keep a test's account files, Keychain entries, and notices together. Attributes: - home: Stand-in home directory. The default accounts directory and the - default profile home resolve inside it. - accounts: The default accounts directory, ``/.aleo/accounts``. - Created by the keystore on first save. - keychain: The in-memory Keychain tool. - notes: Lines the keystore wrote to the terminal. + home: Temporary home used to resolve default account and profile paths. + accounts: Account files created by the test, under ``/.aleo/accounts``. + keychain: In-memory entries available for assertions. + notes: Captured terminal notices, in the order they were written. """ def __init__(self, home: Path) -> None: @@ -81,12 +77,12 @@ def _no_prompt(message: str) -> str: @pytest.fixture(autouse=True) def account_sandbox(request: pytest.FixtureRequest, tmp_path_factory: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch) -> AccountSandbox: - """Keep every test away from the developer's own accounts, profile and Keychain. + """Isolate account tests from real keys and passwords. - A profile finds its account through the account keystore, so a test that - only creates a profile would otherwise read or write ``~/.aleo/accounts``. - Each test gets an empty home directory, the account and profile variables - cleared, an in-memory Keychain and no terminal to prompt on. + Clear account variables, redirect keystore files to a temporary home, + and replace Keychain access with an in-memory fake. Reject prompts so + a missing test password fails instead of waiting for input. Offline + tests also use the temporary home for profile files. """ from aleo.keystore._runtime import runtime @@ -99,9 +95,8 @@ def account_sandbox(request: pytest.FixtureRequest, tmp_path_factory: pytest.Tem monkeypatch.setattr(runtime, "prompt_hidden", _no_prompt) monkeypatch.setattr(runtime, "prompt_visible", _no_prompt) monkeypatch.setattr(runtime, "notify", box.notes.append) - # The live and devnode tiers keep the real home directory in the - # environment: local proving caches its parameters there. The keystore's - # own home lookup is replaced for them all the same. + # Live and devnode tests need the existing proving-parameter cache. + # Keep their HOME while redirecting all keystore access above. if request.node.get_closest_marker("live") is None and request.node.get_closest_marker("devnode") is None: monkeypatch.setenv("HOME", str(box.home)) monkeypatch.setenv("USERPROFILE", str(box.home)) diff --git a/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py b/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py index 62875c9c..238e4893 100644 --- a/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py +++ b/shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py @@ -23,10 +23,8 @@ def test_full_lifecycle_from_fresh_profile(tmp_path, monkeypatch): - # Prove the participant path: credentials must SELF-provision and the - # profile key must be genuinely fresh (a developer shell may carry - # SHIELD_SWAP_PRIVATE_KEY, which would select a funded, already-redeemed - # account and void every "fresh account" assertion below). + # Require onboarding to obtain credentials for a new account. Credentials + # or keys inherited from the shell could skip the stages tested below. monkeypatch.delenv("ALEO_E2E_API_KEY", raising=False) monkeypatch.delenv("ALEO_E2E_CONSUMER_ID", raising=False) monkeypatch.delenv("SHIELD_SWAP_PRIVATE_KEY", raising=False) diff --git a/shield-swap-sdk/tests/integration/test_swap_lifecycle.py b/shield-swap-sdk/tests/integration/test_swap_lifecycle.py index 8be3039d..f1337dc5 100644 --- a/shield-swap-sdk/tests/integration/test_swap_lifecycle.py +++ b/shield-swap-sdk/tests/integration/test_swap_lifecycle.py @@ -222,7 +222,7 @@ def test_concurrent_swaps_reserve_distinct_identities(tmp_path, monkeypatch): monkeypatch.setenv("ALEO_E2E_CONSUMER_ID", cid) monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", os.environ["ALEO_E2E_PRIVATE_KEY"]) dex = ShieldSwap.from_profile(tmp_path / "home") - report = dex.onboard() # uses the funded account; no-op stages skip + report = dex.onboard() # Reuse completed onboarding stages for the funded account. assert report.funded held = {tid: v for tid, v in dex.status().balances.items() if v.get("private", 0) > 0} diff --git a/shield-swap-sdk/tests/test_first_swap_account.py b/shield-swap-sdk/tests/test_first_swap_account.py index a951e25c..9d19425d 100644 --- a/shield-swap-sdk/tests/test_first_swap_account.py +++ b/shield-swap-sdk/tests/test_first_swap_account.py @@ -1,4 +1,4 @@ -"""The runnable example binds its account before scanner or faucet I/O.""" +"""Check that the example reuses its account before contacting a service.""" import json import runpy from pathlib import Path @@ -23,7 +23,7 @@ def test_example_reuses_stored_account_before_network(tmp_path, monkeypatch, acc stored = json.loads(account_file.read_text()) if run == 0: first_address, first_account = saved["address"], account_file.read_bytes() - # The profile names the account; the key stays in the account file. + # A restart must keep both the saved address and its original key. assert saved == {"address": first_address, "account": "default", "network": "testnet", "endpoint": "https://edge.provable.com/api"} assert stored["address"] == first_address and stored["key"]["type"] == "plaintext" diff --git a/shield-swap-sdk/tests/test_gen_context.py b/shield-swap-sdk/tests/test_gen_context.py index f1e8aea2..581856ae 100644 --- a/shield-swap-sdk/tests/test_gen_context.py +++ b/shield-swap-sdk/tests/test_gen_context.py @@ -52,21 +52,5 @@ def test_committed_page_is_current(): def test_page_stays_compact(): - # ~6.5k tokens — cheap context, enforced. Raised 20k → 22k with the - # router-dispatch surface (wrapper_proofs / withdrawal params); 22k → 24k - # when get_pools/get_tokens/derive_pool_key/derive_tick_key picked up full - # docstrings (they rendered blank before); 24k → 26k for the swap/swap_many - # footgun warnings (build-time counter reservation, refusing an unusable - # quote). 24k had been squeezed to 134 chars of headroom, which any further - # edit broke — this is deliberate room, not another squeeze. 26k → 32k - # (2026-09) for the upstream sync: rebalancing (plan + execute, with the - # price-fragility warning agents must relay), fill receipts, the routing - # graph, and the indexer's unclaimed/protocol-state views. 32k → 34k - # (2026-10) for compliance proofs: six write methods gained a - # ``compliance_proofs`` parameter and a one-line note on what it takes. - # 34k → 36k (2026-10-23) for record inventory: ``plan_inventory`` and - # ``rebalance_inventory`` plus the reservation note on ``swap``. - # 36k → 38k (2026-11-17) for the account keystore: ``from_profile`` says - # where the signer's key comes from and what it raises, and the - # existing-account question names the keystore import command. + # Keep the full guide small enough to include in an agent's working context. assert len(_render()) < 38_000 diff --git a/shield-swap-sdk/tests/test_package.py b/shield-swap-sdk/tests/test_package.py index fc1dd453..2803e3e3 100644 --- a/shield-swap-sdk/tests/test_package.py +++ b/shield-swap-sdk/tests/test_package.py @@ -32,7 +32,7 @@ def test_import_guard_names_the_aleo_sdk_upgrade(monkeypatch): import pytest import aleo_shield_swap - aleo_shield_swap._require_aleo_sdk() # the installed sdk has aleo.keystore - monkeypatch.setitem(sys.modules, "aleo.keystore", None) # simulate an aleo-sdk without it + aleo_shield_swap._require_aleo_sdk() # Confirm the installed SDK supports account storage. + monkeypatch.setitem(sys.modules, "aleo.keystore", None) # Exercise the upgrade message for an older SDK. with pytest.raises(ImportError, match=r'needs aleo-sdk>=0\.9\.0 \(found .*\); run: pip install -U "aleo-sdk>=0\.9\.0"'): aleo_shield_swap._require_aleo_sdk() diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index e67c4151..90cd60fe 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -1,9 +1,8 @@ -"""The profile binds one Aleo account and finds its key through ``aleo.keystore``. +"""Check that profiles retain the intended account without exposing its key. -Every test runs inside the ``account_sandbox`` fixture (``conftest.py``): an -empty home directory, the account and profile variables cleared, an in-memory -Keychain and no terminal. Keys are random and never funded; comparisons go -through ``same_secret`` so a failure never prints one. +The account_sandbox fixture supplies temporary files and a fake Keychain. +Accounts are generated for tests and never funded. Use same_secret for key +comparisons so pytest does not include private keys in failure output. """ from __future__ import annotations @@ -23,25 +22,25 @@ from aleo_shield_swap import profile as profile_module from aleo_shield_swap.profile import DEFAULT_ENDPOINT, Profile -# Test-only passwords. Never used for a funded account. +# Fixed passwords for unfunded test accounts. PASSWORD = "correct horse battery staple" OTHER_PASSWORD = "another test password" def new_account() -> SimpleNamespace: - """Return a random account as an address and private-key pair of strings.""" + """Generate an unfunded account for a test.""" key = testnet.PrivateKey.random() return SimpleNamespace(address=str(key.address), private_key=str(key)) def same_secret(actual: object, expected: object) -> None: - """Compare two secrets without putting either into an assertion message.""" + """Fail on unequal secrets without printing either value.""" if not isinstance(actual, str) or actual != expected: raise AssertionError("the secret values differ") def failure(call: Callable[[], Any]) -> KeystoreError: - """Return the keystore error a call fails with.""" + """Capture a failed call so the test can inspect its error code.""" try: call() except KeystoreError as error: @@ -58,7 +57,7 @@ def files_under(*roots: Path) -> list[Path]: def assert_key_on_no_disk(private_key: str, *roots: Path) -> None: - """Assert that no file under *roots* contains the key.""" + """Check for leaked private keys in files below the supplied directories.""" for path in files_under(*roots): if private_key.encode() in path.read_bytes(): raise AssertionError(f"{path} contains a private key") @@ -69,7 +68,7 @@ def saved_profile(home: Path) -> dict[str, Any]: def write_legacy_profile(home: Path, account: SimpleNamespace, **extra: Any) -> Path: - """Write a profile whose ``profile.json`` holds the private key itself.""" + """Create a profile in the older format for compatibility and migration tests.""" home.mkdir(parents=True, exist_ok=True) path = home / "profile.json" data = {"address": account.address, "private_key": account.private_key, @@ -81,13 +80,13 @@ def write_legacy_profile(home: Path, account: SimpleNamespace, **extra: Any) -> @pytest.fixture(autouse=True) def fresh_legacy_notices(monkeypatch): - """Clear the once-per-process record of legacy-key notices before each test.""" + """Let each test observe its own migration warnings.""" monkeypatch.setattr(profile_module, "_legacy_notices", set()) @pytest.fixture def lookups(monkeypatch): - """Count the keystore lookups a test triggers.""" + """Record lookup arguments to check account selection and key caching.""" calls: list[dict[str, Any]] = [] real = keystore.load @@ -99,10 +98,10 @@ def counted(**kwargs: Any): return calls -# ── The test surroundings themselves ───────────────────────────────────────── +# Test isolation def test_tests_run_against_a_stand_in_home(account_sandbox, tmp_path): - """Check that nothing here resolves to the developer's own files.""" + """Verify that the fixture redirects default paths and clears account variables.""" import os assert Path.home() == account_sandbox.home @@ -116,7 +115,7 @@ def test_tests_run_against_a_stand_in_home(account_sandbox, tmp_path): assert stored.path == account_sandbox.accounts / "default.json" -# ── A home with no profile yet ─────────────────────────────────────────────── +# Creating a profile def test_create_then_reload_is_stable(tmp_path): p1 = Profile.load_or_create(tmp_path / "home") @@ -206,7 +205,7 @@ def test_profile_made_from_an_environment_key_needs_it_again(tmp_path, monkeypat Profile.load_or_create(tmp_path / "home") monkeypatch.delenv("ALEO_PRIVATE_KEY") - later = Profile.load_or_create(tmp_path / "home") # loading still works + later = Profile.load_or_create(tmp_path / "home") # The saved address is still available without the key. assert later.address == account.address assert failure(lambda: later.private_key).code == "ACCOUNT_NOT_FOUND" @@ -312,7 +311,7 @@ def test_account_variable_names_the_account_file(tmp_path, monkeypatch, account_ ]) def test_selected_name_is_recorded_when_the_key_comes_from_the_environment( tmp_path, monkeypatch, account_sandbox, argument, variable, recorded): - """No account file exists for a key supplied per run; the name the lookup selected is kept.""" + """Keep the selected name so the same key can later be imported under it.""" monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) if variable is not None: monkeypatch.setenv("ALEO_ACCOUNT", variable) @@ -340,7 +339,7 @@ def test_accounts_dir_is_used_and_not_recorded(tmp_path, account_sandbox): assert not account_sandbox.accounts.exists() assert set(saved_profile(profile.home)) == {"address", "account", "network", "endpoint"} - # The directory is not recorded, so a later run passes it again. + # Reopening from a custom location requires the same directory. same_secret(Profile.load_or_create(tmp_path / "home", accounts_dir=accounts).private_key, profile.private_key) without = Profile.load_or_create(tmp_path / "home") assert failure(lambda: without.private_key).code == "ACCOUNT_NOT_FOUND" @@ -354,7 +353,7 @@ def test_accounts_dir_variable_is_honoured(tmp_path, monkeypatch, account_sandbo same_secret(Profile.load_or_create(tmp_path / "home").private_key, profile.private_key) -# ── Encrypted and Keychain storage ─────────────────────────────────────────── +# Protecting keys with encryption or Keychain def test_encrypted_account_needs_its_password_on_later_runs(tmp_path, monkeypatch, account_sandbox): created = Profile.load_or_create(tmp_path / "home", storage="encrypted", password=PASSWORD) @@ -362,7 +361,7 @@ def test_encrypted_account_needs_its_password_on_later_runs(tmp_path, monkeypatc assert stored["key"]["type"] == "encrypted" assert_key_on_no_disk(created.private_key, tmp_path, account_sandbox.home) - # Loading never needs the password; reading the key does. + # Inspecting an existing profile must not require unlocking its key. locked = Profile.load_or_create(tmp_path / "home") assert locked.address == created.address assert failure(lambda: locked.private_key).code == "PASSWORD_REQUIRED" @@ -430,7 +429,7 @@ def test_keychain_storage_outside_macos_creates_nothing(tmp_path, monkeypatch, a assert account_sandbox.keychain.entries == {} -# ── An existing profile ────────────────────────────────────────────────────── +# Reopening profiles and supporting older files def test_legacy_profile_keeps_working_and_is_left_untouched(tmp_path, account_sandbox): account = new_account() @@ -449,7 +448,7 @@ def test_legacy_profile_is_reported_once(tmp_path, caplog): path = write_legacy_profile(tmp_path / "home", account) with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): first = Profile.load_or_create(tmp_path / "home") - assert caplog.records == [] # nothing until the key is read + assert caplog.records == [] # Warn only when the legacy key is used. first.private_key first.private_key Profile.load_or_create(tmp_path / "home").private_key @@ -473,7 +472,7 @@ def test_each_legacy_profile_is_reported(tmp_path, caplog): def test_migrated_legacy_profile_reads_the_account_file_without_a_notice(tmp_path, caplog, account_sandbox): account = new_account() path = write_legacy_profile(tmp_path / "home", account) - keystore.migrate(path) # the copy in profile.json stays + keystore.migrate(path) # Migration keeps the original key unless removal is requested. with caplog.at_level(logging.WARNING, logger="aleo_shield_swap.profile"): same_secret(Profile.load_or_create(tmp_path / "home").private_key, account.private_key) assert caplog.records == [] @@ -566,7 +565,7 @@ def test_address_only_account_file_needs_the_key_from_the_environment(tmp_path, assert failure(lambda: profile.private_key).code == "KEY_NOT_STORED" -# ── Which account name an existing profile selects ─────────────────────────── +# Choosing the account for a saved profile def test_recorded_account_name_is_used(tmp_path, lookups): created = Profile.load_or_create(tmp_path / "home", account="trading") @@ -582,14 +581,14 @@ def test_account_variable_beats_the_recorded_name(tmp_path, monkeypatch, account profile = Profile.load_or_create(tmp_path / "home") error = failure(lambda: profile.private_key) assert error.code == "ACCOUNT_NOT_FOUND" and "elsewhere.json" in str(error) - # The recorded name is withheld so the keystore applies the variable itself. + # Leave name unset so keystore.load() can use ALEO_ACCOUNT. assert [call["name"] for call in lookups] == [None] - # A second account file holding the same key satisfies the address check. + # Renaming the account is allowed when its address stays the same. keystore.save(created.private_key, name="elsewhere") same_secret(Profile.load_or_create(tmp_path / "home").private_key, created.private_key) - # One holding another key does not. + # An override must not switch the profile to another address. monkeypatch.setenv("ALEO_ACCOUNT", "stranger") keystore.save(new_account().private_key, name="stranger") stranger = Profile.load_or_create(tmp_path / "home") @@ -633,24 +632,24 @@ def test_lookup_passes_the_recorded_address_and_the_legacy_key(tmp_path, lookups same_secret(call["password"], PASSWORD) -# ── One lookup per profile object ──────────────────────────────────────────── +# Unlocking once and retrying failed lookups def test_key_is_resolved_once_per_object_and_only_when_read(tmp_path, lookups): Profile.load_or_create(tmp_path / "home") del lookups[:] profile = Profile.load_or_create(tmp_path / "home") assert profile.address and profile.network and profile.credentials == {} - assert lookups == [] # loading reads no key + assert lookups == [] # Reading metadata does not unlock the account. for _ in range(3): profile.private_key assert len(lookups) == 1 - Profile.load_or_create(tmp_path / "home").private_key # a new object looks again + Profile.load_or_create(tmp_path / "home").private_key # Each new object must load its own key. assert len(lookups) == 2 def test_new_profile_keeps_the_key_it_was_created_with(tmp_path, lookups): profile = Profile.load_or_create(tmp_path / "home", storage="encrypted", password=PASSWORD) - assert len(lookups) == 1 # the lookup that found no account + assert len(lookups) == 1 # Creation first checked for an existing account. profile.private_key profile.private_key assert len(lookups) == 1 @@ -680,7 +679,7 @@ def test_repr_and_saved_profile_hold_no_key(tmp_path): raise AssertionError("the profile exposes a private key") -# ── Callers ────────────────────────────────────────────────────────────────── +# Opening a trading client def test_from_profile_signs_with_the_resolved_key(tmp_path, monkeypatch): account = new_account() @@ -708,7 +707,7 @@ def test_from_profile_reports_a_locked_account(tmp_path, monkeypatch): assert not (tmp_path / "home").exists() -# ── Homes, credentials and the journal ─────────────────────────────────────── +# Profile directories, credentials, and journals def test_env_home_override(tmp_path, monkeypatch): monkeypatch.setenv("SHIELD_SWAP_HOME", str(tmp_path / "envhome")) @@ -739,8 +738,7 @@ def test_journal_path(tmp_path): def test_tilde_in_home_is_expanded(tmp_path, monkeypatch): - """A "~/..." string must not create a literal ~ directory in the cwd — - that would write the profile somewhere no later run looks.""" + """Expand ~ so a restart can find the profile in the expected home directory.""" monkeypatch.setenv("HOME", str(tmp_path)) monkeypatch.chdir(tmp_path) profile = Profile.load_or_create("~/.shield-swap-tilde") From f02446058c407ec29a27198442e66c268efe4d01 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:18:57 -0500 Subject: [PATCH 4/9] fix(shield-swap): reject an account file that is one of the profile's own files With the accounts directory set to the profile home, the account names "profile" and "credentials" select profile.json and credentials.json. Creating the profile then replaced the account file that had just been written, and saving credentials would replace a stored one. Profile.load_or_create() now raises ValueError for that selection before it reads or writes anything. Other account names may still live in the profile home. --- .../python/aleo_shield_swap/profile.py | 42 +++++++++++++++++ shield-swap-sdk/tests/test_profile.py | 47 +++++++++++++++++++ 2 files changed, 89 insertions(+) diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index 17e7aad8..d502317d 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -47,6 +47,42 @@ def _selected_account_name(account: Optional[str]) -> str: return account if account is not None else (os.environ.get("ALEO_ACCOUNT") or "default") +def _same_directory(first: Path, second: Path) -> bool: + """Report whether two paths name one directory, following symbolic links.""" + try: + return os.path.samefile(first, second) + except OSError: + # A directory that does not exist yet is compared by its resolved path. + return os.path.normcase(os.path.realpath(first)) == os.path.normcase(os.path.realpath(second)) + + +def _reject_account_in_profile_files(home: Path, account: Optional[str], + accounts_dir: "Path | str | None") -> None: + """Refuse an account file that is also one of the profile's own files. + + The keystore stores an account as ``.json``. When the accounts + directory is the profile home, the names ``profile`` and ``credentials`` + select ``profile.json`` and ``credentials.json``, and writing either + file would replace the stored key. Reads the environment and resolves + paths; writes nothing. + + Raises: + ValueError: The selected account file is ``profile.json`` or + ``credentials.json`` in ``home``. + """ + name = _selected_account_name(account) + if f"{name}.json" not in (_PROFILE, _CREDENTIALS): + return + # Resolve the directory as the keystore does: argument, variable, then default. + directory = Path(accounts_dir or os.environ.get("ALEO_ACCOUNTS_DIR") + or Path.home() / ".aleo" / "accounts").expanduser() + if _same_directory(directory, home): + raise ValueError( + f'The account "{name}" in {directory} would be stored as {home / (name + ".json")}, ' + "a file this profile writes its own data to. Choose another account name, or an " + "accounts directory other than the profile home.") + + def _report_legacy_key(path: Path, address: str) -> None: """Point callers to the migration command for a key still in profile.json. @@ -203,9 +239,15 @@ def load_or_create(cls, home: "Path | str | None" = None, *, to another account. Other codes identify invalid key sources, names, or unavailable storage. An existing profile reports key errors when :attr:`private_key` is read. + ValueError: The account file would be ``profile.json`` or + ``credentials.json`` in ``home``: the account is named + ``profile`` or ``credentials`` and the accounts directory is + the profile home. Nothing is written. Choose another name or + another accounts directory. """ # Treat ~ as the user's home, including paths passed directly from Python. home = Path(home).expanduser() if home is not None else cls.default_home() + _reject_account_in_profile_files(home, account, accounts_dir) path = home / _PROFILE if path.exists(): path.chmod(0o600) # heal a pre-existing loose mode diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index 90cd60fe..6aae5c3a 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -353,6 +353,53 @@ def test_accounts_dir_variable_is_honoured(tmp_path, monkeypatch, account_sandbo same_secret(Profile.load_or_create(tmp_path / "home").private_key, profile.private_key) +@pytest.mark.parametrize("name", ["profile", "credentials"]) +def test_account_file_that_is_a_profile_file_is_rejected_before_anything_is_written(tmp_path, name): + home = tmp_path / "home" + with pytest.raises(ValueError, match=f"{name}.json"): + Profile.load_or_create(home, accounts_dir=home, account=name) + assert not home.exists() + + +def test_account_file_that_is_a_profile_file_is_rejected_when_the_variables_select_it(tmp_path, monkeypatch): + home = tmp_path / "home" + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", str(home)) + monkeypatch.setenv("ALEO_ACCOUNT", "profile") + with pytest.raises(ValueError, match="profile.json"): + Profile.load_or_create(home) + assert not home.exists() + + +def test_account_file_that_is_a_profile_file_is_rejected_through_another_spelling_of_the_home(tmp_path): + home = tmp_path / "home" + home.mkdir() + (tmp_path / "link").symlink_to(home, target_is_directory=True) + with pytest.raises(ValueError, match="profile.json"): + Profile.load_or_create(home, accounts_dir=tmp_path / "link", account="profile") + assert files_under(home) == [] + + +def test_stored_account_named_like_the_credentials_file_is_left_untouched(tmp_path): + # Saving credentials would replace this account file, so the profile refuses it. + home = tmp_path / "home" + account = new_account() + stored = keystore.save(account.private_key, name="credentials", dir=home) + before = Path(stored.path).read_bytes() + with pytest.raises(ValueError, match="credentials.json"): + Profile.load_or_create(home, accounts_dir=home, account="credentials") + assert files_under(home) == [Path(stored.path)] + assert Path(stored.path).read_bytes() == before + + +def test_other_account_names_may_live_in_the_profile_home(tmp_path): + home = tmp_path / "home" + profile = Profile.load_or_create(home, accounts_dir=home, account="trading") + profile.save_credentials(jwt="token") + reopened = Profile.load_or_create(home, accounts_dir=home) + same_secret(reopened.private_key, profile.private_key) + assert {path.name for path in files_under(home)} == {"profile.json", "credentials.json", "trading.json"} + + # Protecting keys with encryption or Keychain def test_encrypted_account_needs_its_password_on_later_runs(tmp_path, monkeypatch, account_sandbox): From 61897471910eb625bd7a65cf625db7c793574b8b Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:26:29 -0500 Subject: [PATCH 5/9] fix(shield-swap): share swap counters between profile homes of one account Profile homes that select one account now share its key, but each home kept its own journal and counter cursor. On one network, two homes could both reserve counter 0 before either swap finalized and derive the same blinded address; the chain check sees only finalized swaps, so one swap was rejected. ShieldSwap.from_profile() now opens the journal with a counter ledger at ~/.aleo/shield-swap/counters//
.jsonl. Every journal opened with the same ledger reserves and skips counters through it under one lock, so homes that share an account never issue the same counter. The ledger holds counter numbers and timestamps only, in a directory readable by its owner. Swaps and blinding factors stay in each home's journal, and Journal(path) without a ledger behaves as before. --- shield-swap-sdk/README.md | 5 ++ .../python/aleo_shield_swap/client.py | 3 +- .../python/aleo_shield_swap/journal.py | 77 +++++++++++++++---- .../python/aleo_shield_swap/profile.py | 27 +++++++ shield-swap-sdk/tests/conftest.py | 4 + shield-swap-sdk/tests/test_journal.py | 75 ++++++++++++++++++ shield-swap-sdk/tests/test_profile.py | 37 +++++++++ 7 files changed, 213 insertions(+), 15 deletions(-) diff --git a/shield-swap-sdk/README.md b/shield-swap-sdk/README.md index b6a79bba..ccfcd807 100644 --- a/shield-swap-sdk/README.md +++ b/shield-swap-sdk/README.md @@ -79,6 +79,11 @@ 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//
.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; diff --git a/shield-swap-sdk/python/aleo_shield_swap/client.py b/shield-swap-sdk/python/aleo_shield_swap/client.py index 829381b2..bc10db04 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/client.py +++ b/shield-swap-sdk/python/aleo_shield_swap/client.py @@ -235,7 +235,8 @@ def from_profile(cls, home: Any = None, *, pass # offline or scanner down — record methods will surface it dex = cls(aleo) dex.profile = profile - dex.journal = Journal(profile.journal_path) + # The ledger keeps homes that share this account off each other's counters. + dex.journal = Journal(profile.journal_path, counters=profile.counters_path) # Durable ss_ token first — session JWTs are short-lived and stale # ones would shadow a perfectly good API token. if creds.get("dex_api_token"): diff --git a/shield-swap-sdk/python/aleo_shield_swap/journal.py b/shield-swap-sdk/python/aleo_shield_swap/journal.py index 1ed8592f..02568b7c 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/journal.py +++ b/shield-swap-sdk/python/aleo_shield_swap/journal.py @@ -9,6 +9,10 @@ Counter reservation is the concurrency-critical piece: blinded identities must never collide, so counters are issued once, under an advisory file lock, and burned (never reused) when their swap fails. + +Profiles that trade from one account on one network share a counter ledger, +a second JSONL file outside every profile home. A journal opened with that +ledger issues counters through it, so two homes never issue the same one. """ from __future__ import annotations @@ -55,11 +59,19 @@ class Journal: path: Where the log lives, usually ``Profile.journal_path``. Its parent is created on first append, alongside a ``.lock`` sibling used to serialize writers. + counters: Ledger of the counters issued for this journal's account, + usually ``Profile.counters_path``. Every journal opened with the + same ledger issues counters through it, so profile homes that + share an account never issue the same counter. The ledger holds + counter numbers and timestamps only; swaps and blinding factors + stay in *path*. Defaults to None: counters are then coordinated + only among users of *path*. """ - def __init__(self, path: "Path | str") -> None: + def __init__(self, path: "Path | str", *, counters: "Path | str | None" = None) -> None: self.path = Path(path) self._lock_path = self.path.with_suffix(".lock") + self._ledger = Journal(counters) if counters is not None else None def __repr__(self) -> str: return f"Journal({str(self.path)!r})" @@ -113,17 +125,49 @@ def events(self) -> list[dict[str, Any]]: # ── Counters ───────────────────────────────────────────────────────────── + @contextmanager + def _counters_locked(self) -> Iterator[None]: + """Hold every lock a counter change needs. + + Takes the ledger's lock before this journal's, in that order on every + path, so journals sharing a ledger cannot deadlock. Creates the + ledger's directory for its owner only: the file names in it are the + addresses this user trades from. + """ + if self._ledger is None: + with self._locked(): + yield + else: + self._ledger.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) + with self._ledger._locked(), self._locked(): + yield + + def _write_counter_event(self, event: dict[str, Any]) -> None: + """Append a counter event to the ledger, then to this journal. + + The caller holds :meth:`_counters_locked`. The ledger is written + first: a crash between the two writes leaves a counter that no + journal uses, never one that two journals use. + """ + line = json.dumps(event) + "\n" + for journal in (self._ledger, self): + if journal is not None: + with journal.path.open("a") as f: + f.write(line) + def reserve_counters(self, n: int) -> list[int]: - """Issue the next *n* counters, exactly once, under a file lock.""" + """Issue the next *n* counters, exactly once, under a file lock. + + With a counter ledger, the counters are also unique among every + journal that shares the ledger. + """ if n <= 0: return [] - with self._locked(): + with self._counters_locked(): start = self.counter_cursor() counters = list(range(start, start + n)) - event = {"type": "counters_reserved", "ts": time.time(), - "counters": counters} - with self.path.open("a") as f: # already under the lock - f.write(json.dumps(event) + "\n") + self._write_counter_event({"type": "counters_reserved", "ts": time.time(), + "counters": counters}) return counters def skip_counters_through(self, counter: int) -> None: @@ -132,17 +176,21 @@ def skip_counters_through(self, counter: int) -> None: A fresh journal for an account that already swapped starts at 0, but those counters are consumed on chain — a swap built on one is rejected at finalize. The client seeds the cursor past the used run with this; - it never moves the cursor backwards. + it never moves the cursor backwards. With a counter ledger, the run + is retired for every journal that shares the ledger. """ - with self._locked(): + with self._counters_locked(): if counter < self.counter_cursor(): return - event = {"type": "counters_skipped", "ts": time.time(), "through": counter} - with self.path.open("a") as f: # already under the lock - f.write(json.dumps(event) + "\n") + self._write_counter_event({"type": "counters_skipped", "ts": time.time(), + "through": counter}) def counter_cursor(self) -> int: - """Next unissued counter (max seen in any event + 1).""" + """Next unissued counter (max seen in any event + 1). + + With a counter ledger, counts the counters issued to every journal + that shares it as well as this journal's own. + """ top = -1 for e in self.events(): if e["type"] == "counters_reserved": @@ -151,7 +199,8 @@ def counter_cursor(self) -> int: top = max(top, e.get("through", -1)) elif e["type"] in ("swap", "swap_failed"): top = max(top, e.get("counter", -1)) - return top + 1 + cursor = top + 1 + return cursor if self._ledger is None else max(cursor, self._ledger.counter_cursor()) # ── Typed events ───────────────────────────────────────────────────────── diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index d502317d..f078b771 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -47,6 +47,11 @@ def _selected_account_name(account: Optional[str]) -> str: return account if account is not None else (os.environ.get("ALEO_ACCOUNT") or "default") +def _counters_root() -> Path: + """Return the directory of the counter ledgers shared by this user's profile homes.""" + return Path.home() / ".aleo" / "shield-swap" / "counters" + + def _same_directory(first: Path, second: Path) -> bool: """Report whether two paths name one directory, following symbolic links.""" try: @@ -126,6 +131,11 @@ class Profile: profiles selecting the same account name share its key. To trade from another address, use a separate home and ``account`` name, and clear any key variables that still select the first account. + + Homes that share an account on one network issue swap counters through + one file, :attr:`counters_path`, so their swaps never reuse a blinded + identity. Each home keeps its own journal: collect a swap from the home + that made it. """ def __init__(self, home: Path, data: dict[str, Any]) -> None: @@ -399,3 +409,20 @@ def journal_path(self) -> Path: on first append. """ return self.home / "journal.jsonl" + + @property + def counters_path(self) -> Path: + """Where the swap counters issued for this account are recorded. + + The file is ``~/.aleo/shield-swap/counters//
.jsonl``, + outside the profile home. Every profile on this machine that trades + from the same address on the same network shares it, so their swaps + never use the same counter. It holds counter numbers and timestamps; + swaps and their claim secrets stay in :attr:`journal_path`. Its + directory is created for the owner only, because the file names in + it are addresses. + + Returns the path whether or not the file exists — the journal creates + it when it first issues a counter. + """ + return _counters_root() / self.network / f"{self.address}.jsonl" diff --git a/shield-swap-sdk/tests/conftest.py b/shield-swap-sdk/tests/conftest.py index 1c3b67b7..ea5f3f19 100644 --- a/shield-swap-sdk/tests/conftest.py +++ b/shield-swap-sdk/tests/conftest.py @@ -100,6 +100,10 @@ def account_sandbox(request: pytest.FixtureRequest, tmp_path_factory: pytest.Tem if request.node.get_closest_marker("live") is None and request.node.get_closest_marker("devnode") is None: monkeypatch.setenv("HOME", str(box.home)) monkeypatch.setenv("USERPROFILE", str(box.home)) + else: + # Keep counter ledgers out of the real home, which these tests retain. + from aleo_shield_swap import profile + monkeypatch.setattr(profile, "_counters_root", lambda: box.home / ".aleo" / "shield-swap" / "counters") return box diff --git a/shield-swap-sdk/tests/test_journal.py b/shield-swap-sdk/tests/test_journal.py index 8f48985d..3773de13 100644 --- a/shield-swap-sdk/tests/test_journal.py +++ b/shield-swap-sdk/tests/test_journal.py @@ -1,4 +1,5 @@ import json +import stat import threading from aleo_shield_swap.journal import Journal @@ -84,3 +85,77 @@ def test_skip_counters_through_advances_the_cursor(tmp_path): assert Journal(tmp_path / "journal.jsonl").counter_cursor() == 12 j.skip_counters_through(5) # never moves backwards assert j.counter_cursor() == 12 + + +# Journals of one account sharing a counter ledger + +def _on_ledger(tmp_path, home): + """Open the journal of one profile home on the ledger every home shares.""" + return Journal(tmp_path / home / "journal.jsonl", counters=tmp_path / "counters" / "account.jsonl") + + +def test_journals_on_one_ledger_never_issue_the_same_counter(tmp_path): + one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") + assert one.reserve_counters(2) == [0, 1] + assert two.reserve_counters(2) == [2, 3] + assert one.reserve_counters(1) == [4] + assert one.counter_cursor() == two.counter_cursor() == 5 + assert _on_ledger(tmp_path, "three").reserve_counters(1) == [5] # a home opened later + + +def test_ledger_directory_is_readable_by_its_owner_only(tmp_path): + _on_ledger(tmp_path, "one").reserve_counters(1) + assert stat.S_IMODE((tmp_path / "counters").stat().st_mode) == 0o700 + + +def test_journals_on_one_ledger_are_safe_across_threads(tmp_path): + got: list[int] = [] + lock = threading.Lock() + + def grab(home): + counters = _on_ledger(tmp_path, home).reserve_counters(5) + with lock: + got.extend(counters) + + ts = [threading.Thread(target=grab, args=(f"home-{n}",)) for n in range(4)] + [t.start() for t in ts] + [t.join() for t in ts] + assert sorted(got) == list(range(20)) # no counter issued twice + + +def test_skipped_counters_reach_every_journal_on_the_ledger(tmp_path): + one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") + one.skip_counters_through(9) + assert two.counter_cursor() == 10 + assert two.reserve_counters(1) == [10] + two.skip_counters_through(5) # never moves backwards + assert one.counter_cursor() == 11 + + +def test_journal_ahead_of_the_ledger_starts_past_its_own_history(tmp_path): + # A journal that issued counters before it joined a ledger keeps them spent. + Journal(tmp_path / "one" / "journal.jsonl").reserve_counters(8) + one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") + assert one.reserve_counters(1) == [8] + assert two.reserve_counters(1) == [9] + + +def test_each_journal_records_the_counters_it_was_issued(tmp_path): + # Without the ledger file, a journal still never reissues its own counters. + one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") + one.reserve_counters(2) + two.reserve_counters(2) + assert Journal(tmp_path / "two" / "journal.jsonl").counter_cursor() == 4 + assert Journal(tmp_path / "one" / "journal.jsonl").counter_cursor() == 2 + + +def test_ledger_holds_counters_and_nothing_about_the_swaps(tmp_path): + one = _on_ledger(tmp_path, "one") + (counter,) = one.reserve_counters(1) + one.record_swap(_handle("s1"), counter=counter) + one.record_swap_failed(one.reserve_counters(1)[0], "boom") + one.skip_counters_through(6) + events = [json.loads(line) for line in (tmp_path / "counters" / "account.jsonl").read_text().splitlines()] + assert [sorted(event) for event in events] == [ + ["counters", "ts", "type"], ["counters", "ts", "type"], ["through", "ts", "type"]] + assert [h.swap_id for h in one.pending_claims()] == ["s1"] diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index 6aae5c3a..e118aa17 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -746,6 +746,26 @@ def test_from_profile_signs_with_the_resolved_key(tmp_path, monkeypatch): assert saved_profile(tmp_path / "home")["account"] == "default" +def test_clients_of_two_homes_on_one_account_reserve_different_swap_identities(tmp_path, monkeypatch): + aleo = Mock() + aleo.network_name = "testnet" + monkeypatch.setattr("aleo.Aleo", Mock(return_value=aleo)) + monkeypatch.setattr("aleo.HTTPProvider", Mock()) + # No swap has finalized, so the chain reports every blinded address unused. + monkeypatch.setattr(ShieldSwap, "_blinded_address_used", lambda self, blinded_address: False) + monkeypatch.setattr( + "aleo_shield_swap.client.blinded_identity_at", + lambda aleo, account, program, counter: SimpleNamespace(counter=counter, blinded_address=f"ba{counter}")) + + first = ShieldSwap.from_profile(tmp_path / "one") + second = ShieldSwap.from_profile(tmp_path / "two") + assert first.profile.address == second.profile.address + + counters = [identity.counter for dex in (first, second, first) for identity in dex._reserve_identities(object(), 1)] + assert counters == [0, 1, 2] + assert first.journal.path != second.journal.path + + def test_from_profile_reports_a_locked_account(tmp_path, monkeypatch): keystore.save(new_account().private_key, storage="encrypted", password=PASSWORD) monkeypatch.setattr("aleo.Aleo", Mock()) @@ -768,6 +788,23 @@ def test_default_home_is_under_the_home_directory(account_sandbox): assert (account_sandbox.home / ".shield-swap" / "profile.json").exists() +def test_counter_ledger_is_named_by_network_and_address_outside_the_home(tmp_path, account_sandbox): + first = Profile.load_or_create(tmp_path / "one") + second = Profile.load_or_create(tmp_path / "two") + mainnet = Profile.load_or_create(tmp_path / "three", network="mainnet") + counters = account_sandbox.home / ".aleo" / "shield-swap" / "counters" + assert first.counters_path == second.counters_path == counters / "testnet" / f"{first.address}.jsonl" + assert mainnet.counters_path == counters / "mainnet" / f"{mainnet.address}.jsonl" + assert not counters.exists() # reading the path creates nothing + + +def test_counter_ledger_differs_between_accounts(tmp_path): + first = Profile.load_or_create(tmp_path / "one") + other = Profile.load_or_create(tmp_path / "two", account="other") + assert first.address != other.address + assert first.counters_path != other.counters_path + + def test_credentials_roundtrip(tmp_path): p = Profile.load_or_create(tmp_path / "home") assert p.credentials == {} From a7645a7cef4a251d7975d30ad1e2e18538cf6147 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:53:24 -0500 Subject: [PATCH 6/9] fix(shield-swap): publish a journal's earlier counters to the shared ledger A journal that reserved counters before it was opened with a counter ledger kept them to itself. Their swaps may not have finalized, so a second home on the same account could reserve the same counter and derive the same blinded address. Opening a journal with a ledger now retires the journal's own counters in the ledger when the ledger is behind, under the ledger's lock. The same happens after a swap is recorded on an identity the caller chose, which the ledger did not issue. A journal the ledger already covers writes nothing. --- .../python/aleo_shield_swap/journal.py | 39 +++++++++++++++++-- shield-swap-sdk/tests/test_journal.py | 27 +++++++++++++ 2 files changed, 62 insertions(+), 4 deletions(-) diff --git a/shield-swap-sdk/python/aleo_shield_swap/journal.py b/shield-swap-sdk/python/aleo_shield_swap/journal.py index 02568b7c..b8347fea 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/journal.py +++ b/shield-swap-sdk/python/aleo_shield_swap/journal.py @@ -64,14 +64,18 @@ class Journal: same ledger issues counters through it, so profile homes that share an account never issue the same counter. The ledger holds counter numbers and timestamps only; swaps and blinding factors - stay in *path*. Defaults to None: counters are then coordinated - only among users of *path*. + stay in *path*. Opening the journal reads both files and, when + *path* records counters the ledger lacks, retires them in the + ledger. Defaults to None: counters are then coordinated only + among users of *path*. """ def __init__(self, path: "Path | str", *, counters: "Path | str | None" = None) -> None: self.path = Path(path) self._lock_path = self.path.with_suffix(".lock") self._ledger = Journal(counters) if counters is not None else None + # Counters issued before this journal used the ledger may still be pending. + self._publish_counters() def __repr__(self) -> str: return f"Journal({str(self.path)!r})" @@ -155,6 +159,27 @@ def _write_counter_event(self, event: dict[str, Any]) -> None: with journal.path.open("a") as f: f.write(line) + def _publish_counters(self) -> None: + """Retire this journal's counters in the ledger when the ledger is behind. + + A journal holds counters the ledger did not issue when it reserved + them before it was opened with a ledger, or recorded a swap on an + identity the caller chose. Their swaps may not have finalized, so + the chain cannot report them to the other journals; this does. + + Reads both files. Takes the locks and appends one + ``counters_skipped`` event to the ledger only when the ledger is + behind; otherwise writes nothing. + """ + if self._ledger is None or self._own_cursor() <= self._ledger.counter_cursor(): + return + with self._counters_locked(): + through = self._own_cursor() - 1 + if through >= self._ledger.counter_cursor(): + event = {"type": "counters_skipped", "ts": time.time(), "through": through} + with self._ledger.path.open("a") as f: + f.write(json.dumps(event) + "\n") + def reserve_counters(self, n: int) -> list[int]: """Issue the next *n* counters, exactly once, under a file lock. @@ -191,6 +216,11 @@ def counter_cursor(self) -> int: With a counter ledger, counts the counters issued to every journal that shares it as well as this journal's own. """ + cursor = self._own_cursor() + return cursor if self._ledger is None else max(cursor, self._ledger.counter_cursor()) + + def _own_cursor(self) -> int: + """Next counter past every one this journal's own file records.""" top = -1 for e in self.events(): if e["type"] == "counters_reserved": @@ -199,8 +229,7 @@ def counter_cursor(self) -> int: top = max(top, e.get("through", -1)) elif e["type"] in ("swap", "swap_failed"): top = max(top, e.get("counter", -1)) - cursor = top + 1 - return cursor if self._ledger is None else max(cursor, self._ledger.counter_cursor()) + return top + 1 # ── Typed events ───────────────────────────────────────────────────────── @@ -218,6 +247,7 @@ def record_swap(self, handle: SwapHandle, counter: int) -> None: """ self.append("swap", counter=counter, pool_keys=list(handle.pool_keys), **{k: getattr(handle, k) for k in _HANDLE_FIELDS}) + self._publish_counters() # the caller may have chosen the identity def record_swap_failed(self, counter: int, error: str) -> None: """Burn a counter whose swap never landed. @@ -231,6 +261,7 @@ def record_swap_failed(self, counter: int, error: str) -> None: error: Why the swap failed, kept for diagnosis. """ self.append("swap_failed", counter=counter, error=error) + self._publish_counters() def record_claim(self, swap_id: str, transaction_id: str, amount_out: int) -> None: diff --git a/shield-swap-sdk/tests/test_journal.py b/shield-swap-sdk/tests/test_journal.py index 3773de13..043b6071 100644 --- a/shield-swap-sdk/tests/test_journal.py +++ b/shield-swap-sdk/tests/test_journal.py @@ -140,6 +140,33 @@ def test_journal_ahead_of_the_ledger_starts_past_its_own_history(tmp_path): assert two.reserve_counters(1) == [9] +def test_opening_a_journal_on_a_ledger_publishes_the_counters_it_already_issued(tmp_path): + # Counters reserved before the ledger existed may belong to swaps that have not finalized. + assert Journal(tmp_path / "one" / "journal.jsonl").reserve_counters(2) == [0, 1] + _on_ledger(tmp_path, "one") # opened, never asked for a counter + assert _on_ledger(tmp_path, "two").reserve_counters(1) == [2] + + +def test_opening_a_new_journal_on_a_ledger_writes_nothing(tmp_path): + _on_ledger(tmp_path, "one") + assert list(tmp_path.iterdir()) == [] + + +def test_reopening_a_journal_on_a_ledger_publishes_its_counters_once(tmp_path): + Journal(tmp_path / "one" / "journal.jsonl").reserve_counters(2) + for _ in range(3): + _on_ledger(tmp_path, "one") + assert len((tmp_path / "counters" / "account.jsonl").read_text().splitlines()) == 1 + + +def test_swap_recorded_on_a_caller_chosen_counter_reaches_the_ledger(tmp_path): + one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") + one.record_swap(_handle("s1"), counter=7) # an identity the ledger did not issue + assert two.reserve_counters(1) == [8] + two.record_swap_failed(11, "boom") + assert one.reserve_counters(1) == [12] + + def test_each_journal_records_the_counters_it_was_issued(tmp_path): # Without the ledger file, a journal still never reissues its own counters. one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") From 23995b73e11bd92940cfe03c2075623d440a2687 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:53:24 -0500 Subject: [PATCH 7/9] fix(shield-swap): check the saved account name against the profile's files The check for an account file that is profile.json or credentials.json ran before the existing profile was read, so it missed the name saved in the profile. A profile saved for the account "credentials" and reopened with the accounts directory set to its home loaded the key, and save_credentials() then rewrote the account file. Profile.load_or_create() now applies the check to the saved name when neither the account argument nor ALEO_ACCOUNT selects another one. --- .../python/aleo_shield_swap/profile.py | 15 ++++-- shield-swap-sdk/tests/test_profile.py | 49 +++++++++++++++++++ 2 files changed, 59 insertions(+), 5 deletions(-) diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index f078b771..555e32e1 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -61,7 +61,7 @@ def _same_directory(first: Path, second: Path) -> bool: return os.path.normcase(os.path.realpath(first)) == os.path.normcase(os.path.realpath(second)) -def _reject_account_in_profile_files(home: Path, account: Optional[str], +def _reject_account_in_profile_files(home: Path, name: str, accounts_dir: "Path | str | None") -> None: """Refuse an account file that is also one of the profile's own files. @@ -75,7 +75,6 @@ def _reject_account_in_profile_files(home: Path, account: Optional[str], ValueError: The selected account file is ``profile.json`` or ``credentials.json`` in ``home``. """ - name = _selected_account_name(account) if f"{name}.json" not in (_PROFILE, _CREDENTIALS): return # Resolve the directory as the keystore does: argument, variable, then default. @@ -252,12 +251,14 @@ def load_or_create(cls, home: "Path | str | None" = None, *, ValueError: The account file would be ``profile.json`` or ``credentials.json`` in ``home``: the account is named ``profile`` or ``credentials`` and the accounts directory is - the profile home. Nothing is written. Choose another name or - another accounts directory. + the profile home. The name is the one that selects the + account, including the name saved in an existing profile. + Nothing is written. Choose another name or another accounts + directory. """ # Treat ~ as the user's home, including paths passed directly from Python. home = Path(home).expanduser() if home is not None else cls.default_home() - _reject_account_in_profile_files(home, account, accounts_dir) + _reject_account_in_profile_files(home, _selected_account_name(account), accounts_dir) path = home / _PROFILE if path.exists(): path.chmod(0o600) # heal a pre-existing loose mode @@ -266,6 +267,10 @@ def load_or_create(cls, home: "Path | str | None" = None, *, profile._account = account profile._accounts_dir = accounts_dir profile._password = password + # The name saved in the profile selects the account when nothing else does. + saved = profile._data.get("account") + if account is None and not os.environ.get("ALEO_ACCOUNT") and isinstance(saved, str): + _reject_account_in_profile_files(home, saved, accounts_dir) else: import aleo from aleo import keystore diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index e118aa17..eb0abfe8 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -20,6 +20,7 @@ from aleo_shield_swap import ShieldSwap from aleo_shield_swap import profile as profile_module +from aleo_shield_swap.journal import Journal from aleo_shield_swap.profile import DEFAULT_ENDPOINT, Profile # Fixed passwords for unfunded test accounts. @@ -391,6 +392,35 @@ def test_stored_account_named_like_the_credentials_file_is_left_untouched(tmp_pa assert Path(stored.path).read_bytes() == before +def test_saved_account_name_that_selects_a_profile_file_is_rejected_on_reopening(tmp_path, account_sandbox): + home = tmp_path / "home" + Profile.load_or_create(home, account="credentials") + moved = home / "credentials.json" + (account_sandbox.accounts / "credentials.json").rename(moved) + before = moved.read_bytes() + # The saved name selects the account here, without the argument or the variable. + with pytest.raises(ValueError, match="credentials.json"): + Profile.load_or_create(home, accounts_dir=home) + assert moved.read_bytes() == before + + +def test_saved_account_name_gives_way_to_the_variable_when_checking_profile_files(tmp_path, monkeypatch): + home = tmp_path / "home" + Profile.load_or_create(home, account="credentials") + other = Profile.load_or_create(tmp_path / "other-home", accounts_dir=home, account="trading") + monkeypatch.setenv("ALEO_ACCOUNT", "trading") + reopened = Profile.load_or_create(tmp_path / "other-home", accounts_dir=home) + same_secret(reopened.private_key, other.private_key) + + +def test_account_named_like_a_profile_file_works_outside_the_profile_home(tmp_path): + profile = Profile.load_or_create(tmp_path / "home", account="credentials") + profile.save_credentials(jwt="token") + reopened = Profile.load_or_create(tmp_path / "home") + same_secret(reopened.private_key, profile.private_key) + assert reopened.credentials == {"jwt": "token"} + + def test_other_account_names_may_live_in_the_profile_home(tmp_path): home = tmp_path / "home" profile = Profile.load_or_create(home, accounts_dir=home, account="trading") @@ -766,6 +796,25 @@ def test_clients_of_two_homes_on_one_account_reserve_different_swap_identities(t assert first.journal.path != second.journal.path +def test_client_of_a_second_home_skips_counters_an_earlier_journal_still_has_pending(tmp_path, monkeypatch): + aleo = Mock() + aleo.network_name = "testnet" + monkeypatch.setattr("aleo.Aleo", Mock(return_value=aleo)) + monkeypatch.setattr("aleo.HTTPProvider", Mock()) + # The earlier swaps have not finalized, so the chain cannot report their counters. + monkeypatch.setattr(ShieldSwap, "_blinded_address_used", lambda self, blinded_address: False) + monkeypatch.setattr( + "aleo_shield_swap.client.blinded_identity_at", + lambda aleo, account, program, counter: SimpleNamespace(counter=counter, blinded_address=f"ba{counter}")) + # A journal that reserved counters before the ledger existed. + profile = Profile.load_or_create(tmp_path / "one") + assert Journal(profile.journal_path).reserve_counters(2) == [0, 1] + + ShieldSwap.from_profile(tmp_path / "one") + second = ShieldSwap.from_profile(tmp_path / "two") + assert [identity.counter for identity in second._reserve_identities(object(), 1)] == [2] + + def test_from_profile_reports_a_locked_account(tmp_path, monkeypatch): keystore.save(new_account().private_key, storage="encrypted", password=PASSWORD) monkeypatch.setattr("aleo.Aleo", Mock()) From 6a1074dd7bf11ea68e491aa43561504fbcdcf103 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:59:37 -0500 Subject: [PATCH 8/9] fix(shield-swap): take one lock when a journal and its ledger share a lock file A journal and its counter ledger each lock the file their name gives once the suffix is replaced with .lock, so journal.jsonl and journal.counters in one directory lock the same file. Reserving a counter took that lock twice through two handles and waited forever. A counter change now compares the two open lock files and takes a single lock when they are the same file. --- .../python/aleo_shield_swap/journal.py | 26 +++++++++++++++---- shield-swap-sdk/tests/test_journal.py | 17 ++++++++++++ 2 files changed, 38 insertions(+), 5 deletions(-) diff --git a/shield-swap-sdk/python/aleo_shield_swap/journal.py b/shield-swap-sdk/python/aleo_shield_swap/journal.py index b8347fea..57cfa374 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/journal.py +++ b/shield-swap-sdk/python/aleo_shield_swap/journal.py @@ -18,6 +18,7 @@ import fcntl import json +import os import time from contextlib import contextmanager from pathlib import Path @@ -134,17 +135,32 @@ def _counters_locked(self) -> Iterator[None]: """Hold every lock a counter change needs. Takes the ledger's lock before this journal's, in that order on every - path, so journals sharing a ledger cannot deadlock. Creates the + path, so journals sharing a ledger cannot deadlock. Takes one lock + when both are the same file. Creates the ledger's directory for its owner only: the file names in it are the addresses this user trades from. """ if self._ledger is None: with self._locked(): yield - else: - self._ledger.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - with self._ledger._locked(), self._locked(): - yield + return + self._ledger.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) + self.path.parent.mkdir(parents=True, exist_ok=True) + with self._ledger._lock_path.open("a") as outer, self._lock_path.open("a") as inner: + # Two file names can derive one lock file, such as journal.jsonl and + # journal.counters. A second lock on it would wait on the first forever. + shared = os.path.sameopenfile(outer.fileno(), inner.fileno()) + fcntl.flock(outer, fcntl.LOCK_EX) + try: + if not shared: + fcntl.flock(inner, fcntl.LOCK_EX) + try: + yield + finally: + if not shared: + fcntl.flock(inner, fcntl.LOCK_UN) + finally: + fcntl.flock(outer, fcntl.LOCK_UN) def _write_counter_event(self, event: dict[str, Any]) -> None: """Append a counter event to the ledger, then to this journal. diff --git a/shield-swap-sdk/tests/test_journal.py b/shield-swap-sdk/tests/test_journal.py index 043b6071..9f9a367a 100644 --- a/shield-swap-sdk/tests/test_journal.py +++ b/shield-swap-sdk/tests/test_journal.py @@ -167,6 +167,23 @@ def test_swap_recorded_on_a_caller_chosen_counter_reaches_the_ledger(tmp_path): assert one.reserve_counters(1) == [12] +def test_journal_and_ledger_that_derive_one_lock_file_do_not_deadlock(tmp_path): + # Both names lose their suffix to ".lock", so the two locks are one file. + got: list[int] = [] + + def reserve(): + for home in ("one", "one"): + journal = Journal(tmp_path / home / "journal.jsonl", counters=tmp_path / home / "journal.counters") + got.extend(journal.reserve_counters(2)) + journal.skip_counters_through(got[-1] + 1) + + worker = threading.Thread(target=reserve, daemon=True) + worker.start() + worker.join(timeout=10) + assert not worker.is_alive() # a second lock on the same file would wait forever + assert got == [0, 1, 3, 4] + + def test_each_journal_records_the_counters_it_was_issued(tmp_path): # Without the ledger file, a journal still never reissues its own counters. one, two = _on_ledger(tmp_path, "one"), _on_ledger(tmp_path, "two") From b6c5b46f11b720e7cfbedcd2f1ac04f325a49a2a Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Tue, 17 Nov 2026 11:59:37 -0500 Subject: [PATCH 9/9] fix(shield-swap): adopt the account a concurrent startup stored Two processes that opened new profile homes for the same missing account could both find no account and both generate a key. The second save then failed with ACCOUNT_EXISTS and its profile was not created. Profile.load_or_create() now loads the stored account when its own save loses that race. The key it generated was never written. --- .../python/aleo_shield_swap/profile.py | 26 +++++++++---- shield-swap-sdk/tests/test_profile.py | 37 +++++++++++++++++++ 2 files changed, 56 insertions(+), 7 deletions(-) diff --git a/shield-swap-sdk/python/aleo_shield_swap/profile.py b/shield-swap-sdk/python/aleo_shield_swap/profile.py index 555e32e1..d4deecf7 100644 --- a/shield-swap-sdk/python/aleo_shield_swap/profile.py +++ b/shield-swap-sdk/python/aleo_shield_swap/profile.py @@ -193,7 +193,8 @@ def load_or_create(cls, home: "Path | str | None" = None, *, The profile records its address, account name, network, and endpoint in ``profile.json``. Creating it does not contact the network or move - funds. An existing profile keeps its recorded settings and can be + funds. When several processes create the same missing account at + once, one key is saved and every profile uses it. An existing profile keeps its recorded settings and can be opened without a password; its key is unlocked on the first read of :attr:`private_key`. @@ -275,11 +276,15 @@ def load_or_create(cls, home: "Path | str | None" = None, *, import aleo from aleo import keystore net = getattr(aleo, network) - try: + + def existing() -> "tuple[str, str, str]": loaded = keystore.load(name=account, dir=accounts_dir, password=password) - private_key, address = loaded.private_key, loaded.address # Remember the account name even when the key is supplied per run. name = loaded.stored.name if loaded.stored is not None else _selected_account_name(account) + return loaded.private_key, loaded.address, name + + try: + private_key, address, name = existing() except keystore.KeystoreError as error: if error.code != "ACCOUNT_NOT_FOUND" or not create: raise @@ -290,10 +295,17 @@ def load_or_create(cls, home: "Path | str | None" = None, *, 'after this process exits. Choose "plaintext", "keychain" or "encrypted".', ) from None private_key = str(net.PrivateKey.random()) - stored = keystore.save(private_key, name=account, dir=accounts_dir, - storage=cast(Any, storage), # save() validates storage. - password=password, save_password=save_password) - address, name = stored.address, stored.name + try: + stored = keystore.save(private_key, name=account, dir=accounts_dir, + storage=cast(Any, storage), # save() validates storage. + password=password, save_password=save_password) + address, name = stored.address, stored.name + except keystore.KeystoreError as lost: + if lost.code != "ACCOUNT_EXISTS": + raise + # Another process stored this account after the lookup found + # none. Use its key; the key generated here was never saved. + private_key, address, name = existing() home.mkdir(parents=True, exist_ok=True) data = {"address": address, "account": name, "network": network, "endpoint": endpoint} diff --git a/shield-swap-sdk/tests/test_profile.py b/shield-swap-sdk/tests/test_profile.py index eb0abfe8..2bf0b596 100644 --- a/shield-swap-sdk/tests/test_profile.py +++ b/shield-swap-sdk/tests/test_profile.py @@ -168,6 +168,43 @@ def test_new_profile_adopts_the_stored_account(tmp_path, account_sandbox): assert saved_profile(profile.home)["account"] == "default" +def test_account_stored_by_a_concurrent_startup_is_adopted(tmp_path, monkeypatch, account_sandbox): + winner = new_account() + real = keystore.load + + def racing(**kwargs: Any): + try: + return real(**kwargs) + except KeystoreError: + # Another process stores the account after this lookup found none. + if not (account_sandbox.accounts / "default.json").exists(): + keystore.save(winner.private_key) + raise + + monkeypatch.setattr(keystore, "load", racing) + profile = Profile.load_or_create(tmp_path / "home") + assert profile.address == winner.address + same_secret(profile.private_key, winner.private_key) + assert saved_profile(profile.home)["address"] == winner.address + assert [path.name for path in account_sandbox.accounts.iterdir() if path.suffix == ".json"] == ["default.json"] + + +def test_locked_account_stored_by_a_concurrent_startup_is_reported(tmp_path, monkeypatch, account_sandbox): + real = keystore.load + + def racing(**kwargs: Any): + try: + return real(**kwargs) + except KeystoreError: + if not (account_sandbox.accounts / "default.json").exists(): + keystore.save(new_account().private_key, storage="encrypted", password=PASSWORD) + raise + + monkeypatch.setattr(keystore, "load", racing) + assert failure(lambda: Profile.load_or_create(tmp_path / "home")).code == "PASSWORD_REQUIRED" + assert not (tmp_path / "home").exists() + + def test_two_homes_share_the_stored_account(tmp_path): first = Profile.load_or_create(tmp_path / "one") second = Profile.load_or_create(tmp_path / "two")