spacerouter-cli 0.2.2__tar.gz → 0.3.0b1__tar.gz

{spacerouter_cli-0.2.2 → spacerouter_cli-0.3.0b1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: spacerouter-cli
-Version: 0.2.2
+Version: 0.3.0b1
 Summary: CLI for the Space Router residential proxy network — designed for AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: rich<14.0,>=13.0
-Requires-Dist: spacerouter>=0.2.0
+Requires-Dist: spacerouter>=0.3.0b1
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'

{spacerouter_cli-0.2.2 → spacerouter_cli-0.3.0b1}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spacerouter-cli"
-version = "0.2.2"
+version = "0.3.0b1"
 description = "CLI for the Space Router residential proxy network — designed for AI agents"
 requires-python = ">=3.10"
 license = "MIT"
 dependencies = [
     "typer>=0.12,<1.0",
     "httpx>=0.27,<1.0",
-    "spacerouter>=0.2.0",
+    "spacerouter>=0.3.0b1",
     "rich>=13.0,<14.0",
 ]
 

{spacerouter_cli-0.2.2 → spacerouter_cli-0.3.0b1}/src/spacerouter_cli/__init__.py

@@ -1,3 +1,3 @@
 """SpaceRouter CLI — AI-agent-friendly tool for residential proxy requests."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0b1"

spacerouter_cli-0.3.0b1/src/spacerouter_cli/commands/escrow.py

@@ -0,0 +1,236 @@
+"""``spacerouter escrow`` — TokenPaymentEscrow wallet operations.
+
+Consumer-facing view of on-chain balance and withdrawal state. JSON
+output only (agent-friendly). Read operations work without a private
+key; deposits / withdrawals require one via ``--private-key`` or
+``SR_ESCROW_PRIVATE_KEY``.
+
+This command group operates against the on-chain contract directly.
+For a provider's *local* receipt state (signed/failed/retryable),
+see the provider CLI at
+``python -m app.main --receipts`` on the node.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Optional
+
+import typer
+
+from spacerouter.escrow import EscrowClient
+from spacerouter_cli.output import cli_error_handler, print_json
+
+app = typer.Typer(
+    help="Query and interact with the TokenPaymentEscrow contract on-chain.",
+    no_args_is_help=True,
+)
+
+
+ENV_RPC = "SR_ESCROW_CHAIN_RPC"
+ENV_CONTRACT = "SR_ESCROW_CONTRACT_ADDRESS"
+ENV_PRIVATE_KEY = "SR_ESCROW_PRIVATE_KEY"
+
+
+RpcOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        "--rpc-url",
+        help=(
+            "Creditcoin RPC endpoint. Env: SR_ESCROW_CHAIN_RPC. "
+            "Default test: https://rpc.cc3-testnet.creditcoin.network"
+        ),
+    ),
+]
+ContractOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        "--contract-address",
+        help="TokenPaymentEscrow proxy address. Env: SR_ESCROW_CONTRACT_ADDRESS.",
+    ),
+]
+PrivateKeyOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        "--private-key",
+        help=(
+            "Wallet private key for write operations. "
+            "Env: SR_ESCROW_PRIVATE_KEY. Never log or commit."
+        ),
+    ),
+]
+
+
+def _resolve_client(
+    rpc_url: Optional[str],
+    contract_address: Optional[str],
+    private_key: Optional[str] = None,
+) -> EscrowClient:
+    rpc = rpc_url or os.environ.get(ENV_RPC)
+    contract = contract_address or os.environ.get(ENV_CONTRACT)
+    key = private_key or os.environ.get(ENV_PRIVATE_KEY)
+
+    if not rpc:
+        raise typer.BadParameter(
+            "Missing RPC URL. Use --rpc-url or set SR_ESCROW_CHAIN_RPC.",
+        )
+    if not contract:
+        raise typer.BadParameter(
+            "Missing contract address. Use --contract-address or set "
+            "SR_ESCROW_CONTRACT_ADDRESS.",
+        )
+    return EscrowClient(
+        rpc_url=rpc, contract_address=contract, private_key=key,
+    )
+
+
+@app.command("balance")
+@cli_error_handler
+def balance(
+    address: Annotated[
+        str, typer.Argument(help="Address to query escrow balance for."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Escrow balance for an address, in wei (18-decimal SPACE)."""
+    client = _resolve_client(rpc_url, contract_address)
+    wei = client.balance(address)
+    print_json({
+        "address": address,
+        "escrow_balance_wei": wei,
+        "escrow_balance_space": wei / 10**18,
+    })
+
+
+@app.command("token-balance")
+@cli_error_handler
+def token_balance(
+    address: Annotated[
+        str, typer.Argument(help="Address to query undeposited token balance for."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Undeposited (wallet-held) SPACE token balance in wei."""
+    client = _resolve_client(rpc_url, contract_address)
+    wei = client.token_balance(address)
+    print_json({
+        "address": address,
+        "token_balance_wei": wei,
+        "token_balance_space": wei / 10**18,
+    })
+
+
+@app.command("withdrawal-request")
+@cli_error_handler
+def withdrawal_request(
+    address: Annotated[
+        str, typer.Argument(help="Address whose pending withdrawal to inspect."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Pending withdrawal state: amount + unlock timestamp."""
+    client = _resolve_client(rpc_url, contract_address)
+    amount, unlock_at, exists = client.withdrawal_request(address)
+    print_json({
+        "address": address,
+        "has_pending_withdrawal": exists,
+        "amount_wei": amount,
+        "amount_space": amount / 10**18,
+        "unlock_at_epoch_seconds": unlock_at,
+    })
+
+
+@app.command("withdrawal-delay")
+@cli_error_handler
+def withdrawal_delay(
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Contract-wide withdrawal delay in seconds."""
+    client = _resolve_client(rpc_url, contract_address)
+    delay = client.withdrawal_delay()
+    print_json({
+        "withdrawal_delay_seconds": delay,
+        "withdrawal_delay_days": delay / 86400,
+    })
+
+
+@app.command("deposit")
+@cli_error_handler
+def deposit(
+    amount_wei: Annotated[
+        int,
+        typer.Argument(help="Amount to deposit, in wei (18-decimal)."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+    private_key: PrivateKeyOpt = None,
+) -> None:
+    """Deposit tokens into the escrow. Requires a private key."""
+    client = _resolve_client(rpc_url, contract_address, private_key)
+    tx_hash = client.deposit(int(amount_wei))
+    print_json({
+        "action": "deposit",
+        "amount_wei": int(amount_wei),
+        "tx_hash": tx_hash,
+        "from": client.address,
+    })
+
+
+@app.command("initiate-withdrawal")
+@cli_error_handler
+def initiate_withdrawal(
+    amount_wei: Annotated[
+        int,
+        typer.Argument(help="Amount to withdraw, in wei."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+    private_key: PrivateKeyOpt = None,
+) -> None:
+    """Start a withdrawal. Subject to the contract's withdrawal delay."""
+    client = _resolve_client(rpc_url, contract_address, private_key)
+    tx_hash = client.initiate_withdrawal(int(amount_wei))
+    print_json({
+        "action": "initiate_withdrawal",
+        "amount_wei": int(amount_wei),
+        "tx_hash": tx_hash,
+        "from": client.address,
+    })
+
+
+@app.command("execute-withdrawal")
+@cli_error_handler
+def execute_withdrawal(
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+    private_key: PrivateKeyOpt = None,
+) -> None:
+    """Finalise a previously-initiated withdrawal after the delay has elapsed."""
+    client = _resolve_client(rpc_url, contract_address, private_key)
+    tx_hash = client.execute_withdrawal()
+    print_json({
+        "action": "execute_withdrawal",
+        "tx_hash": tx_hash,
+        "from": client.address,
+    })
+
+
+@app.command("cancel-withdrawal")
+@cli_error_handler
+def cancel_withdrawal(
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+    private_key: PrivateKeyOpt = None,
+) -> None:
+    """Cancel a pending withdrawal request before it unlocks."""
+    client = _resolve_client(rpc_url, contract_address, private_key)
+    tx_hash = client.cancel_withdrawal()
+    print_json({
+        "action": "cancel_withdrawal",
+        "tx_hash": tx_hash,
+        "from": client.address,
+    })

spacerouter_cli-0.3.0b1/src/spacerouter_cli/commands/receipts.py

@@ -0,0 +1,76 @@
+"""``spacerouter receipts`` — on-chain receipt state queries.
+
+Consumer-facing view. Given a client address + request UUID, check
+whether the escrow has settled that receipt on-chain. JSON output
+only.
+
+For a provider's *local* receipt state (signed vs failed vs locked),
+see the provider CLI at ``python -m app.main --receipts`` on the
+node — that operates against the provider's local SQLite, not the
+chain.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Optional
+
+import typer
+
+from spacerouter_cli.commands.escrow import (
+    ContractOpt, RpcOpt, _resolve_client,
+)
+from spacerouter_cli.output import cli_error_handler, print_json
+
+app = typer.Typer(
+    help=(
+        "Query on-chain Leg 2 receipt state. For provider-local "
+        "receipt state, run `python -m app.main --receipts` on the node."
+    ),
+    no_args_is_help=True,
+)
+
+
+@app.command("is-settled")
+@cli_error_handler
+def is_settled(
+    client_address: Annotated[
+        str, typer.Argument(help="Receipt client (payer) address."),
+    ],
+    request_uuid: Annotated[
+        str, typer.Argument(help="Receipt UUID (per-client nonce)."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Check whether a specific receipt has been claimed on-chain."""
+    client = _resolve_client(rpc_url, contract_address)
+    used = client.is_nonce_used(client_address, request_uuid)
+    print_json({
+        "client_address": client_address,
+        "request_uuid": request_uuid,
+        "settled_on_chain": used,
+    })
+
+
+@app.command("show")
+@cli_error_handler
+def show(
+    client_address: Annotated[
+        str, typer.Argument(help="Receipt client (payer) address."),
+    ],
+    request_uuid: Annotated[
+        str, typer.Argument(help="Receipt UUID."),
+    ],
+    rpc_url: RpcOpt = None,
+    contract_address: ContractOpt = None,
+) -> None:
+    """Alias for ``is-settled`` — returns the same on-chain state."""
+    client = _resolve_client(rpc_url, contract_address)
+    used = client.is_nonce_used(client_address, request_uuid)
+    print_json({
+        "client_address": client_address,
+        "request_uuid": request_uuid,
+        "settled_on_chain": used,
+        "status": "claimed" if used else "unclaimed_on_chain",
+    })

{spacerouter_cli-0.2.2 → spacerouter_cli-0.3.0b1}/src/spacerouter_cli/main.py

@@ -7,7 +7,10 @@ import json
 import typer
 
 from spacerouter_cli import __version__
-from spacerouter_cli.commands import api_key, billing, config_cmd, dashboard, node, request, status
+from spacerouter_cli.commands import (
+    api_key, billing, config_cmd, dashboard, escrow, node, receipts,
+    request, status,
+)
 
 app = typer.Typer(
     name="spacerouter",
@@ -22,6 +25,8 @@ app.add_typer(node.app, name="node", help="Manage proxy nodes")
 app.add_typer(billing.app, name="billing", help="Billing and checkout")
 app.add_typer(dashboard.app, name="dashboard", help="Dashboard data")
 app.add_typer(config_cmd.app, name="config", help="Configuration management")
+app.add_typer(escrow.app, name="escrow", help="Escrow wallet / deposit / withdrawal")
+app.add_typer(receipts.app, name="receipts", help="On-chain Leg 2 receipt state queries")
 app.command(name="status", help="Check service health")(status.status)
 
 

spacerouter_cli-0.3.0b1/tests/test_escrow_cli.py

@@ -0,0 +1,152 @@
+"""Tests for ``spacerouter escrow`` and ``spacerouter receipts`` sub-apps."""
+
+from __future__ import annotations
+
+from unittest.mock import patch, MagicMock
+
+import pytest
+from typer.testing import CliRunner
+
+from spacerouter_cli.main import app
+from tests.conftest import parse_json_output
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+@pytest.fixture
+def escrow_env(monkeypatch):
+    monkeypatch.setenv("SR_ESCROW_CHAIN_RPC",
+                       "https://rpc.cc3-testnet.creditcoin.network")
+    monkeypatch.setenv("SR_ESCROW_CONTRACT_ADDRESS",
+                       "0xC5740e4e9175301a24FB6d22bA184b8ec0762852")
+
+
+@pytest.fixture
+def mock_escrow_client():
+    """Patch EscrowClient so no real RPC calls go out."""
+    with patch(
+        "spacerouter_cli.commands.escrow.EscrowClient"
+    ) as cls:
+        inst = MagicMock()
+        cls.return_value = inst
+        yield inst
+
+
+class TestEscrowBalance:
+    def test_balance_emits_wei_and_space(
+        self, runner, escrow_env, mock_escrow_client,
+    ):
+        mock_escrow_client.balance.return_value = 5 * 10**18
+        result = runner.invoke(app, [
+            "escrow", "balance", "0xabcd" + "0" * 36,
+        ])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["escrow_balance_wei"] == 5 * 10**18
+        assert data["escrow_balance_space"] == 5.0
+
+    def test_balance_requires_rpc(self, runner, monkeypatch):
+        monkeypatch.delenv("SR_ESCROW_CHAIN_RPC", raising=False)
+        monkeypatch.delenv("SR_ESCROW_CONTRACT_ADDRESS", raising=False)
+        result = runner.invoke(app, [
+            "escrow", "balance", "0xabcd" + "0" * 36,
+        ])
+        assert result.exit_code != 0
+
+
+class TestWithdrawalRequest:
+    def test_pending_withdrawal_fields(
+        self, runner, escrow_env, mock_escrow_client,
+    ):
+        mock_escrow_client.withdrawal_request.return_value = (
+            10**18, 1_800_000_000, True,
+        )
+        result = runner.invoke(app, [
+            "escrow", "withdrawal-request", "0x" + "a" * 40,
+        ])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["has_pending_withdrawal"] is True
+        assert data["amount_wei"] == 10**18
+        assert data["amount_space"] == 1.0
+        assert data["unlock_at_epoch_seconds"] == 1_800_000_000
+
+
+class TestWithdrawalDelay:
+    def test_surfaces_days(self, runner, escrow_env, mock_escrow_client):
+        mock_escrow_client.withdrawal_delay.return_value = 5 * 86400
+        result = runner.invoke(app, ["escrow", "withdrawal-delay"])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["withdrawal_delay_seconds"] == 432_000
+        assert data["withdrawal_delay_days"] == 5.0
+
+
+class TestDeposit:
+    def test_deposit_returns_tx_hash(
+        self, runner, escrow_env, mock_escrow_client, monkeypatch,
+    ):
+        monkeypatch.setenv("SR_ESCROW_PRIVATE_KEY", "0x" + "f" * 64)
+        mock_escrow_client.deposit.return_value = "0xabc123"
+        mock_escrow_client.address = "0x" + "a" * 40
+        result = runner.invoke(app, ["escrow", "deposit", "1000000000000000000"])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["tx_hash"] == "0xabc123"
+        assert data["action"] == "deposit"
+        mock_escrow_client.deposit.assert_called_once_with(10**18)
+
+
+class TestReceiptsIsSettled:
+    def test_returns_on_chain_state(
+        self, runner, escrow_env, mock_escrow_client,
+    ):
+        mock_escrow_client.is_nonce_used.return_value = True
+        result = runner.invoke(app, [
+            "receipts", "is-settled",
+            "0x" + "a" * 40,
+            "9f8e5c21-1234-4567-89ab-cdef01234567",
+        ])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["settled_on_chain"] is True
+        assert data["request_uuid"] == "9f8e5c21-1234-4567-89ab-cdef01234567"
+
+    def test_unsettled_returns_false(
+        self, runner, escrow_env, mock_escrow_client,
+    ):
+        mock_escrow_client.is_nonce_used.return_value = False
+        result = runner.invoke(app, [
+            "receipts", "is-settled",
+            "0x" + "a" * 40,
+            "11111111-2222-3333-4444-555555555555",
+        ])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["settled_on_chain"] is False
+
+
+class TestReceiptsShow:
+    def test_emits_status_field(
+        self, runner, escrow_env, mock_escrow_client,
+    ):
+        mock_escrow_client.is_nonce_used.return_value = False
+        result = runner.invoke(app, [
+            "receipts", "show",
+            "0x" + "b" * 40,
+            "22222222-3333-4444-5555-666666666666",
+        ])
+        assert result.exit_code == 0
+        data = parse_json_output(result.output)
+        assert data["status"] == "unclaimed_on_chain"
+
+
+class TestSubAppsRegistered:
+    def test_escrow_appears_in_help(self, runner):
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        assert "escrow" in result.output
+        assert "receipts" in result.output