openclaw-algorand-plugin 0.5.0

package/skills/algorand-python/references/use-algokit-utils-reference.md

@@ -0,0 +1,350 @@
+# AlgorandClient (Python)
+
+The main entry point for interacting with Algorand in Python applications.
+
+## Installation
+
+```bash
+pip install algokit-utils
+```
+
+## Creating an AlgorandClient
+
+```python
+from algokit_utils import AlgorandClient
+
+# From environment variables (recommended for production)
+algorand = AlgorandClient.from_environment()
+
+# Default LocalNet configuration
+algorand = AlgorandClient.default_localnet()
+
+# TestNet using AlgoNode free tier
+algorand = AlgorandClient.testnet()
+
+# MainNet using AlgoNode free tier
+algorand = AlgorandClient.mainnet()
+
+# From existing clients
+algorand = AlgorandClient.from_clients(algod=algod, indexer=indexer, kmd=kmd)
+
+# From custom configuration
+from algokit_utils import AlgoClientNetworkConfig
+
+algorand = AlgorandClient.from_config(
+    algod_config=AlgoClientNetworkConfig(
+        server="http://localhost",
+        port="4001",
+        token="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    )
+)
+```
+
+## Accessing SDK Clients
+
+```python
+algod_client = algorand.client.algod
+indexer_client = algorand.client.indexer
+kmd_client = algorand.client.kmd
+```
+
+## Account Management
+
+### Getting Accounts
+
+```python
+# From environment variable (DEPLOYER_MNEMONIC)
+deployer = algorand.account.from_environment("DEPLOYER")
+
+# Random account (for testing)
+random_account = algorand.account.random()
+
+# From mnemonic
+account = algorand.account.from_mnemonic("abandon abandon...")
+
+# From KMD (LocalNet)
+kmd_account = algorand.account.from_kmd("wallet-name", "password")
+```
+
+### Registering Signers
+
+```python
+# Register a signer for automatic signing
+algorand.set_signer_from_account(account)
+
+# Set default signer for all transactions
+algorand.set_default_signer(account.signer)
+```
+
+## Sending Transactions
+
+### Single Transactions
+
+```python
+from algokit_utils import AlgoAmount, PaymentParams, AssetTransferParams
+from algokit_utils import AssetOptInParams, AssetCreateParams
+
+# Payment
+result = algorand.send.payment(
+    PaymentParams(
+        sender="SENDERADDRESS",
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+    )
+)
+
+# Asset transfer
+algorand.send.asset_transfer(
+    AssetTransferParams(
+        sender="SENDERADDRESS",
+        receiver="RECEIVERADDRESS",
+        asset_id=12345,
+        amount=100,
+    )
+)
+
+# Asset opt-in
+algorand.send.asset_opt_in(
+    AssetOptInParams(
+        sender="SENDERADDRESS",
+        asset_id=12345,
+    )
+)
+
+# Asset create
+create_result = algorand.send.asset_create(
+    AssetCreateParams(
+        sender="SENDERADDRESS",
+        total=1_000_000,
+        decimals=6,
+        asset_name="My Token",
+        unit_name="MTK",
+    )
+)
+asset_id = create_result.asset_id
+```
+
+### Transaction Groups
+
+```python
+result = (
+    algorand
+    .new_group()
+    .add_payment(
+        PaymentParams(
+            sender="SENDERADDRESS",
+            receiver="RECEIVERADDRESS",
+            amount=AlgoAmount(algo=1),
+        )
+    )
+    .add_asset_opt_in(
+        AssetOptInParams(
+            sender="SENDERADDRESS",
+            asset_id=12345,
+        )
+    )
+    .send()
+)
+```
+
+### Creating Transactions (Without Sending)
+
+```python
+payment = algorand.create_transaction.payment(
+    PaymentParams(
+        sender="SENDERADDRESS",
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+    )
+)
+# payment is an unsigned algosdk.Transaction
+```
+
+## Common Transaction Parameters
+
+All transactions support these common parameters:
+
+```python
+algorand.send.payment(
+    PaymentParams(
+        sender="SENDERADDRESS",
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+
+        # Optional parameters
+        note=b"My note",
+        lease="unique-lease-id",
+        rekey_to="NEWADDRESS",
+
+        # Fee management
+        static_fee=AlgoAmount(micro_algo=1000),
+        extra_fee=AlgoAmount(micro_algo=1000),  # For covering inner txn fees
+        max_fee=AlgoAmount(micro_algo=10000),
+
+        # Validity
+        validity_window=1000,
+        first_valid_round=12345,
+    )
+)
+```
+
+## App Calls
+
+### Using Typed App Clients (Recommended)
+
+```python
+# Get typed factory from generated client
+factory = algorand.client.get_typed_app_factory(MyContractFactory)
+
+# Deploy
+result = factory.deploy(sender=deployer.address)
+app_client = result.app_client
+
+# Call methods
+response = app_client.send.my_method(
+    sender=deployer.address,
+    args={"param1": "value"},
+)
+```
+
+### Generic App Calls
+
+```python
+from algokit_utils import AppCallMethodCallParams
+from algosdk.abi import Method
+
+algorand.send.app_call_method_call(
+    AppCallMethodCallParams(
+        sender="SENDERADDRESS",
+        app_id=12345,
+        method=Method.from_signature("hello(string)string"),
+        args=["World"],
+    )
+)
+```
+
+## Send Parameters
+
+Control execution behavior when sending:
+
+```python
+from algokit_utils import SendParams
+
+algorand.send.payment(
+    PaymentParams(
+        sender="SENDERADDRESS",
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+    ),
+    send_params=SendParams(
+        # Wait for confirmation
+        max_rounds_to_wait_for_confirmation=5,
+
+        # Suppress logging
+        suppress_log=True,
+
+        # Auto-populate app call resources
+        populate_app_call_resources=True,
+
+        # Auto-calculate inner txn fees
+        cover_app_call_inner_transaction_fees=True,
+    )
+)
+```
+
+## Amount Helpers
+
+```python
+from algokit_utils import AlgoAmount
+
+AlgoAmount(algo=1)           # 1 Algo = 1,000,000 microAlgo
+AlgoAmount(algo=0.5)         # 0.5 Algo = 500,000 microAlgo
+AlgoAmount(micro_algo=1000)  # 1000 microAlgo
+
+# Access values
+amount = AlgoAmount(algo=1)
+amount.algo        # 1.0
+amount.micro_algo  # 1000000
+```
+
+## Common Patterns
+
+### Fund an Account
+
+```python
+algorand.send.payment(
+    PaymentParams(
+        sender=funder_account.address,
+        receiver=new_account.address,
+        amount=AlgoAmount(algo=10),
+    )
+)
+```
+
+### Create and Fund in One Group
+
+```python
+new_account = algorand.account.random()
+
+(
+    algorand
+    .new_group()
+    .add_payment(
+        PaymentParams(
+            sender=funder.address,
+            receiver=new_account.address,
+            amount=AlgoAmount(algo=1),
+        )
+    )
+    .add_asset_opt_in(
+        AssetOptInParams(
+            sender=new_account.address,
+            asset_id=12345,
+        )
+    )
+    .send()
+)
+```
+
+### Deploy and Fund Contract
+
+```python
+factory = algorand.client.get_typed_app_factory(MyContractFactory)
+result = factory.deploy(sender=deployer.address)
+app_client = result.app_client
+
+# Fund the app account for box storage
+algorand.send.payment(
+    PaymentParams(
+        sender=deployer.address,
+        receiver=app_client.app_address,
+        amount=AlgoAmount(algo=1),
+    )
+)
+```
+
+### Using Environment-Based Accounts
+
+```python
+# Set environment variables:
+# DEPLOYER_MNEMONIC="word1 word2 ... word25"
+
+algorand = AlgorandClient.from_environment()
+deployer = algorand.account.from_environment("DEPLOYER")
+
+# Now use deployer for transactions
+algorand.send.payment(
+    PaymentParams(
+        sender=deployer.address,
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+    )
+)
+```
+
+## References
+
+- [AlgoKit Utils Python Overview](https://dev.algorand.co/algokit/utils/python/overview/)
+- [AlgorandClient API](https://dev.algorand.co/reference/algokit-utils-py/api/algorand/)
+- [Transaction Composer](https://dev.algorand.co/algokit/utils/python/transaction-composer/)
+- [Account Management](https://dev.algorand.co/algokit/utils/python/account/)

package/skills/algorand-python/references/use-algokit-utils.md

@@ -0,0 +1,76 @@
+# AlgoKit Utils (Python)
+
+AlgoKit Utils for Python is the primary library for building Algorand applications in Python. It provides a high-level, ergonomic interface via the `AlgorandClient` class, which is the single entry point for interacting with the Algorand network -- sending transactions, managing accounts, deploying smart contracts, and more.
+
+## Installation
+
+```bash
+pip install algokit-utils
+```
+
+## Quick Start
+
+### 1. Create an AlgorandClient
+
+```python
+from algokit_utils import AlgorandClient
+
+# Connect to LocalNet (development)
+algorand = AlgorandClient.default_localnet()
+
+# Connect to TestNet
+algorand = AlgorandClient.testnet()
+
+# Connect to MainNet
+algorand = AlgorandClient.mainnet()
+
+# From environment variables (recommended for production)
+algorand = AlgorandClient.from_environment()
+```
+
+### 2. Get and Register an Account
+
+```python
+# Get a random account (testing)
+account = algorand.account.random()
+
+# From environment variable (e.g. DEPLOYER_MNEMONIC)
+deployer = algorand.account.from_environment("DEPLOYER")
+
+# Register the signer so transactions are automatically signed
+algorand.set_signer_from_account(account)
+```
+
+### 3. Send a Transaction
+
+```python
+from algokit_utils import AlgoAmount, PaymentParams
+
+result = algorand.send.payment(
+    PaymentParams(
+        sender=account.address,
+        receiver="RECEIVERADDRESS",
+        amount=AlgoAmount(algo=1),
+    )
+)
+```
+
+## Key Rules
+
+1. **Always use `AlgorandClient`** as the single entry point. Do not instantiate lower-level SDK clients directly.
+2. **Use `AlgorandClient.from_environment()`** for production deployments and CI/CD pipelines.
+3. **Register signers** with `algorand.set_signer_from_account(account)` before sending transactions so signing is handled automatically.
+4. **Use `AlgoAmount`** for all amounts (e.g. `AlgoAmount(algo=1)`, `AlgoAmount(micro_algo=1000)`) instead of raw numbers to avoid unit conversion errors.
+
+## Reference
+
+For the full AlgorandClient API covering client creation, account management, transaction sending, app calls, transaction groups, amount helpers, and common patterns:
+
+[AlgorandClient Reference](./use-algokit-utils-reference.md)
+
+## External Links
+
+- [AlgoKit Utils Python Overview](https://dev.algorand.co/algokit/utils/python/overview/)
+- [AlgorandClient API Reference](https://dev.algorand.co/reference/algokit-utils-py/api/algorand/)
+- [Transaction Composer](https://dev.algorand.co/algokit/utils/python/transaction-composer/)
+- [Account Management](https://dev.algorand.co/algokit/utils/python/account/)

package/skills/algorand-typescript/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: algorand-typescript
+description: Comprehensive guide for Algorand TypeScript (PuyaTs) smart contract development — syntax rules, migration, testing, deployment, React frontends, AlgoKit Utils, ARC standards, and troubleshooting. This is the parent skill for all TypeScript-specific Algorand content. Use when writing TypeScript contract code, encountering Puya compiler errors, migrating from TEALScript or beta, testing contracts with Vitest, deploying with typed clients, building React frontends, or using AlgoKit Utils in TypeScript. Strong triggers include "Puya compiler error", "uint64", "clone()", "BoxMap", ".algo.ts", "migrate from TEALScript", "algorandFixture", "vitest", "deploy contract", "call method", "React frontend", "use-wallet", "AlgorandClient TypeScript", "npm install algokit-utils".
+---
+
+# Algorand TypeScript
+
+This is the aggregated parent skill for all TypeScript-specific Algorand development. Use the reference files below to find detailed guidance for each topic.
+
+## Quick Start
+
+```bash
+# Create TypeScript project
+algokit init -n my-project -t typescript --answer preset_name production --defaults
+
+# Install AlgoKit Utils
+npm install @algorandfoundation/algokit-utils
+
+# Development cycle
+algokit project run build    # Compile .algo.ts contracts
+algokit project run test     # Run Vitest tests
+```
+
+### Key TypeScript Rule
+
+Contract files must use `.algo.ts` extension. Use AVM types (`uint64`, `bytes`), never JavaScript `number`. Always `clone()` complex types.
+
+## Reference Guide
+
+Navigate to the appropriate reference based on your task. Each topic has one or more files.
+
+### Algorand TypeScript Syntax
+
+Critical syntax rules for Algorand TypeScript (PuyaTs) that prevent compiler errors.
+
+- [algorand-typescript-syntax.md](./references/algorand-typescript-syntax.md) — Core syntax rules overview
+- [algorand-typescript-syntax-reference.md](./references/algorand-typescript-syntax-reference.md) — Full reference index
+- [algorand-typescript-syntax-types-and-values.md](./references/algorand-typescript-syntax-types-and-values.md) — AVM types, numbers, clone(), value semantics
+- [algorand-typescript-syntax-storage.md](./references/algorand-typescript-syntax-storage.md) — GlobalState, LocalState, BoxMap, MBR funding
+- [algorand-typescript-syntax-methods-and-abi.md](./references/algorand-typescript-syntax-methods-and-abi.md) — Decorators, lifecycle methods, visibility
+- [algorand-typescript-syntax-transactions.md](./references/algorand-typescript-syntax-transactions.md) — Group transactions (gtxn), inner transactions (itxn)
+
+### Migration to Algorand TypeScript 1.0
+
+Migrate from TEALScript or Algorand TypeScript Beta to 1.0.
+
+- [algorand-ts-migration.md](./references/algorand-ts-migration.md) — Migration workflow and quick reference
+- [algorand-ts-migration-from-tealscript.md](./references/algorand-ts-migration-from-tealscript.md) — TEALScript migration guide
+- [algorand-ts-migration-from-beta.md](./references/algorand-ts-migration-from-beta.md) — Beta migration guide
+
+### Testing Smart Contracts
+
+Write integration and unit tests using algorandFixture and Vitest.
+
+- [test-smart-contracts.md](./references/test-smart-contracts.md) — Testing patterns and canonical examples
+- [test-smart-contracts-examples.md](./references/test-smart-contracts-examples.md) — Complete test examples
+- [test-smart-contracts-unit-tests.md](./references/test-smart-contracts-unit-tests.md) — Unit testing guide
+
+### Calling Smart Contracts
+
+Deploy and interact with contracts using generated TypeScript clients.
+
+- [call-smart-contracts.md](./references/call-smart-contracts.md) — Deployment and interaction workflow
+- [call-smart-contracts-reference.md](./references/call-smart-contracts-reference.md) — CLI commands reference
+
+### React Frontends
+
+Build React frontends with wallet integration and typed contract clients.
+
+- [deploy-react-frontend.md](./references/deploy-react-frontend.md) — Frontend workflow and signer pattern
+- [deploy-react-frontend-reference.md](./references/deploy-react-frontend-reference.md) — API reference
+- [deploy-react-frontend-examples.md](./references/deploy-react-frontend-examples.md) — Complete code examples
+
+### Creating TypeScript Projects
+
+Initialize TypeScript AlgoKit projects with proper templates and presets.
+
+- [create-project.md](./references/create-project.md) — TypeScript project creation
+- [create-project-reference.md](./references/create-project-reference.md) — TypeScript presets and templates
+
+### Building Smart Contracts (TypeScript)
+
+TypeScript-specific contract building with PuyaTs.
+
+- [build-smart-contracts.md](./references/build-smart-contracts.md) — TypeScript contract building guide
+- [build-smart-contracts-reference.md](./references/build-smart-contracts-reference.md) — TypeScript repos and patterns
+
+### AlgoKit Utils (TypeScript)
+
+Interact with Algorand from TypeScript applications.
+
+- [use-algokit-utils.md](./references/use-algokit-utils.md) — TypeScript AlgoKit Utils overview
+- [use-algokit-utils-reference.md](./references/use-algokit-utils-reference.md) — AlgorandClient TypeScript API reference
+
+### Implementing ARC Standards (TypeScript)
+
+TypeScript implementations of ARC-4, ARC-32, and ARC-56.
+
+- [implement-arc-standards.md](./references/implement-arc-standards.md) — TypeScript ARC overview
+- [implement-arc-standards-arc4.md](./references/implement-arc-standards-arc4.md) — TypeScript ARC-4 implementations
+- [implement-arc-standards-arc32-arc56.md](./references/implement-arc-standards-arc32-arc56.md) — TypeScript typed client usage
+
+### Troubleshooting Errors (TypeScript)
+
+TypeScript-specific error diagnosis and fixes.
+
+- [troubleshoot-errors.md](./references/troubleshoot-errors.md) — TypeScript error overview
+- [troubleshoot-errors-contract.md](./references/troubleshoot-errors-contract.md) — Contract errors with TypeScript fixes
+- [troubleshoot-errors-transaction.md](./references/troubleshoot-errors-transaction.md) — Transaction errors with TypeScript fixes
+
+## Topic Quick Reference
+
+| Topic | Files | Description |
+| ----- | ----- | ----------- |
+| Syntax Rules | 6 | PuyaTs types, storage, methods, transactions |
+| Migration | 3 | TEALScript and beta migration guides |
+| Testing | 3 | Vitest integration and unit tests |
+| Calling Contracts | 2 | Deployment and typed client interaction |
+| React Frontends | 3 | Wallet integration and dApp UI |
+| Create Project | 2 | TypeScript template initialization |
+| Build Contracts | 2 | TypeScript-focused contract building |
+| AlgoKit Utils | 2 | AlgorandClient TypeScript API |
+| ARC Standards | 3 | TypeScript ARC implementations |
+| Troubleshoot | 3 | TypeScript error fixes |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the topic `.md`** file for step-by-step guidance
+3. **Consult detail files** for specific subtopics (syntax, examples, reference)
+4. **For language-agnostic content** (CLI, ARC specs, general workflows), see the `algorand-development` parent skill