Metadata-Version: 2.4
Name: aplane
Version: 0.8.1
Summary: Python SDK for APlane transaction signing
Author: APlane Project LLC
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/aplane-algo/aplane
Project-URL: Documentation, https://github.com/aplane-algo/aplane/tree/main/sdk/python
Project-URL: Repository, https://github.com/aplane-algo/aplane
Keywords: algorand,blockchain,signing,post-quantum,falcon
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: py-algorand-sdk>=2.0.0
Requires-Dist: paramiko>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# APlane Python SDK

Python SDK for signing Algorand transactions via apsignerd.

SDK package versions are tracked independently across languages. Use the compatibility notes in each release rather than assuming Go, Python, and TypeScript package versions will match exactly.

## Installation

```bash
pip install aplane
```

The published package is `aplane` on PyPI.

Or install from source:

```bash
cd sdk/python
pip install -e .
```

## Quick Start

```python
from aplane import SignerClient, send_raw_transaction
from algosdk import transaction
from algosdk.v2client import algod

# Connect to signer (reads config.yaml and token from data dir)
client = SignerClient.from_env()

# Build transaction with algosdk
algod_client = algod.AlgodClient("", "https://testnet-api.4160.nodely.dev")
params = algod_client.suggested_params()

txn = transaction.PaymentTxn(
    sender="SENDER_ADDRESS",
    sp=params,
    receiver="RECEIVER_ADDRESS",
    amt=1000000  # 1 ALGO
)

# Sign via apsignerd (waits for operator approval)
signed = client.sign_transaction(txn)

# Submit to network (signed is ready to use, no processing needed)
txid = send_raw_transaction(algod_client, signed)
print(f"Submitted: {txid}")
```

## Connection Methods

All SDK connections use the configured SSH-backed signer path. Direct local HTTP connection is not a supported SDK mode.

### Environment-Based Connection (Recommended)

Load configuration from a data directory. The directory is required — pass
`data_dir` or set the `APCLIENT_DATA` environment variable:

```python
# Set environment variable
# export APCLIENT_DATA=~/aplane/apclient

client = SignerClient.from_env()

# Or pass directly
client = SignerClient.from_env(data_dir="~/aplane/apclient")
```

Data directory structure (installer default: `~/aplane/apclient`):
```
<data_dir>/
  config.yaml          # Connection settings
  aplane.token         # Authentication token
  .ssh/
    id_ed25519         # SSH private key for authentication
    known_hosts        # Trusted server host keys
```

Example `config.yaml`:
```yaml
signer_port: 11270
ssh:
  host: localhost            # Change to remote host if signer is on another machine
  port: 1127
  identity_file: .ssh/id_ed25519
  known_hosts_path: .ssh/known_hosts
```

### Direct SSH Connection

Connect explicitly via SSH tunnel with 2FA:

```python
client = SignerClient.connect_ssh(
    host="signer.example.com",
    token="your-token",           # used for both SSH auth and HTTP API
    ssh_key_path="~/.ssh/id_ed25519",
    ssh_port=1127,                # default: 1127
    signer_port=11270,            # default: 11270
    timeout=90                    # seconds, default
)
```

**Note**: SSH uses 2FA (token + public key). The token is passed as the SSH
username. Keys are enrolled via the `request-token` operator-approved flow.

The SSH tunnel is established automatically. Remember to close when done:

```python
client.close()
```

Or use as a context manager:

```python
with SignerClient.connect_ssh(host="...", token="...", ssh_key_path="...") as client:
    signed = client.sign_transaction(txn)
# Tunnel closed automatically
```

## Authentication

The recommended way to obtain a token is via the `request-token` flow, which enrolls your SSH key and provisions a token in a single operator-approved step. The token is saved automatically to `$APCLIENT_DATA/aplane.token`.

If your token was provisioned separately (e.g. copied by the operator), you can load it explicitly:

```python
from aplane import load_token

token = load_token("/path/to/apclient/aplane.token")
```

## API Reference

### SignerClient

#### `health() -> bool`

Check if signer is reachable.

```python
if client.health():
    print("Signer is online")
```

#### `list_keys() -> List[KeyInfo]`

List available signing keys.

```python
keys = client.list_keys()
for key in keys:
    print(f"{key.address} [{key.key_type}]")
```

Returns list of `KeyInfo`:
- `address`: Algorand address
- `key_type`: "ed25519", "falcon1024-v1", "timelock-v1", etc.
- `lsig_size`: LogicSig size (for budget calculation)
- `is_generic_lsig`: True if no cryptographic signature needed
- `runtime_args`: List of `RuntimeArg` for generic LogicSigs (name, arg_type, description)

**Discovering required arguments for generic LogicSigs:**

```python
key_info = client.get_key_info(hashlock_address)
if key_info.runtime_args:
    for arg in key_info.runtime_args:
        print(f"{arg.name}: {arg.arg_type} - {arg.description}")
```

#### `sign_transaction(txn, auth_address=None, lsig_args=None) -> str`

Sign a single transaction. Returns a base64-encoded string ready for submission.

The server automatically handles fee pooling for large LogicSigs (e.g., Falcon-1024) by adding dummy transactions as needed.

```python
# Basic signing (uses txn.sender as auth_address)
signed = client.sign_transaction(txn)

# Rekeyed account (different auth key)
signed = client.sign_transaction(txn, auth_address="SIGNER_KEY_ADDRESS")

# Generic LogicSig with runtime args (e.g., HTLC)
signed = client.sign_transaction(
    txn,
    auth_address="HASHLOCK_ADDRESS",
    lsig_args={"preimage": b"secret_value"}
)

# Submit directly (no processing needed)
txid = send_raw_transaction(algod_client, signed)
```

#### `sign_transactions(txns, auth_addresses=None, lsig_args_map=None) -> str`

Sign multiple transactions as a group. Returns a base64-encoded string of concatenated signed transactions, ready for submission.

**Important**: Do NOT pre-assign group IDs. The server computes the group ID after adding any required dummy transactions for large LogicSigs.

```python
# Build transactions (do NOT call assign_group_id)
txn1 = transaction.PaymentTxn(sender=addr1, sp=params, receiver=addr2, amt=100000)
txn2 = transaction.PaymentTxn(sender=addr2, sp=params, receiver=addr1, amt=100000)

# Sign group (server handles grouping and dummies)
signed = client.sign_transactions([txn1, txn2])

# Submit directly (no processing needed)
txid = algod_client.send_raw_transaction(signed)
```

#### `sign_transactions_list(txns, auth_addresses=None, lsig_args_map=None) -> List[str]`

Like `sign_transactions()` but returns individual base64-encoded transactions instead of concatenated. Useful when you need to inspect transactions individually.

```python
signed_list = client.sign_transactions_list([txn1, txn2])
# signed_list is List[str], each element is a base64-encoded signed transaction
```

#### `close()`

Close the client and SSH tunnel (if any).

```python
client.close()
```

## Supported Key Types

| Key Type | Description | Notes |
|----------|-------------|-------|
| `ed25519` | Native Algorand keys | Standard signing |
| `falcon1024-v*` | Post-quantum LogicSig | Signature in LogicSig.Args[0] |
| `timelock-v*` | Time-locked funds | No signature, TEAL-only |
| `htlc-v*` | Hash-locked funds | Requires `preimage` arg (check `runtime_args`) |

The server assembles the complete signed transaction - the SDK returns a base64 string ready for submission.

## Error Handling

### Signing Exceptions

```python
from aplane import (
    SignerError,
    AuthenticationError,
    SigningRejectedError,
    SignerUnavailableError,
    KeyNotFoundError
)

try:
    signed = client.sign_transaction(txn)
except AuthenticationError:
    print("Invalid token")
except SigningRejectedError:
    print("Operator rejected the request")
except SignerUnavailableError:
    print("Signer not reachable or locked")
except KeyNotFoundError:
    print("Key not found in signer")
except SignerError as e:
    print(f"Signing failed: {e}")
```

### Submission Exceptions

`send_raw_transaction()` wraps verbose algod errors into clean exceptions:

```python
from aplane import (
    send_raw_transaction,
    TransactionRejectedError,
    LogicSigRejectedError,
    InsufficientFundsError,
    InvalidTransactionError
)

try:
    txid = send_raw_transaction(algod_client, signed)
except LogicSigRejectedError as e:
    print(f"LogicSig failed: {e.reason}")  # e.txid also available
except InsufficientFundsError as e:
    print(f"Not enough funds: {e.reason}")
except InvalidTransactionError as e:
    print(f"Invalid transaction: {e.reason}")
except TransactionRejectedError as e:
    print(f"Rejected: {e.reason}")
```

## Example: Complete Workflow

```python
#!/usr/bin/env python3
from aplane import SignerClient, load_token, SignerError, send_raw_transaction
from algosdk import transaction
from algosdk.v2client import algod

def main():
    # Load token
    token = load_token("~/aplane/apclient/aplane.token")

    # Connect via SSH (token is used as SSH username for 2FA)
    with SignerClient.connect_ssh(
        host="signer.example.com",
        token=token,
        ssh_key_path="~/.ssh/id_ed25519"
    ) as client:

        # List keys
        keys = client.list_keys()
        sender = keys[0].address
        print(f"Using: {sender}")

        # Build transaction
        algod_client = algod.AlgodClient("", "https://testnet-api.4160.nodely.dev")
        params = algod_client.suggested_params()

        txn = transaction.PaymentTxn(
            sender=sender,
            sp=params,
            receiver=sender,
            amt=0
        )

        # Sign (will wait for operator approval)
        try:
            signed = client.sign_transaction(txn)
            print("Signed!")

            # Submit directly (no processing needed)
            txid = send_raw_transaction(algod_client, signed)
            print(f"TxID: {txid}")

            # Wait for confirmation
            result = transaction.wait_for_confirmation(algod_client, txid, 4)
            print(f"Confirmed in round {result['confirmed-round']}")

        except SignerError as e:
            print(f"Failed: {e}")

if __name__ == "__main__":
    main()
```

## Fee Pooling (Large LogicSigs)

Algorand limits LogicSig size to 1000 bytes per transaction. Large signatures like Falcon-1024 (~3000 bytes) exceed this limit.

**Solution**: The server automatically creates dummy transactions to expand the LogicSig budget pool. Each transaction in a group contributes 1000 bytes to the shared pool.

### How It Works (Server-Side)

1. Server detects key's `lsig_size` exceeds available budget
2. Server calculates dummies needed: `ceil(total_lsig_bytes / 1000) - num_txns`
3. Server creates dummy self-payment transactions (0 amount, min fee)
4. Server distributes dummy fees across LogicSig transactions in the group
5. Server computes group ID and signs all transactions
6. SDK returns concatenated signed group ready for submission

### Example: Falcon-1024 Key

```python
# Falcon-1024 has lsig_size ~3035 bytes, needs 3 dummies
# Total group: 1 main + 3 dummies = 4 transactions
# Pool budget: 4 x 1000 = 4000 bytes (enough for 3035)

params = algod_client.suggested_params()
txn = transaction.PaymentTxn(sender=falcon_addr, sp=params, receiver=receiver, amt=1000000)

# Server automatically adds dummies - just sign and submit
signed = client.sign_transaction(txn)
txid = send_raw_transaction(algod_client, signed)
```

### Fee Impact

| Key Type | LogicSig Size | Dummies Needed | Extra Fee |
|----------|---------------|----------------|-----------|
| Ed25519 | 0 | 0 | 0 |
| Falcon-1024 | ~3035 | 3 | ~3000 uA |

The extra fee covers the dummy transactions required for post-quantum security.

## License

AGPL-3.0-or-later

## Project

This SDK is part of the APlane project:

- Repository: https://github.com/aplane-algo/aplane
- SDK path: `sdk/python`

APlane is an open-source project stewarded by the APlane Project.

See the repository [README](https://github.com/aplane-algo/aplane/blob/main/README.md) for project overview and alpha-status guidance, and [DISCLAIMER.md](https://github.com/aplane-algo/aplane/blob/main/DISCLAIMER.md) for risk, liability, and usage information.
