AgentSkillsCN

call-smart-contracts

使用 AlgoKit CLI 和生成的 TypeScript 客户端部署并交互 Algorand 智能合约。当需要将合约部署至 localnet/测试网/主网、调用合约方法、读取全局/局部/盒状状态、选择加入或退出应用程序，或编写交互脚本时，可使用此技能。强烈触发条件包括：“部署合约”、“调用 increment 方法”、“读取合约状态”、“选择加入应用”、“编写交互脚本”、“通过 ID 获取 TypedAppClient”。

SKILL.md
--- frontmatter
name: call-smart-contracts
description: Deploy and interact with Algorand smart contracts using AlgoKit CLI and generated TypeScript clients. Use when deploying contracts to localnet/testnet/mainnet, calling contract methods, reading global/local/box state, opting in or closing out of applications, or writing interaction scripts. Strong triggers include "deploy the contract", "call the increment method", "read the contract state", "opt into the app", "write a script to interact", "getTypedAppClientById".

Calling Smart Contracts

Deploy and interact with Algorand smart contracts using AlgoKit CLI and the generated TypeScript client.

Overview / Core Workflow

  1. •Build the contract: algokit project run build
  2. •Deploy using CLI: algokit project deploy localnet
  3. •Write TypeScript scripts using the generated client
  4. •Run scripts: npx tsx scripts/my-script.ts

How to proceed

1. Build the Contract

bash
algokit project run build

This compiles your contract and generates:

  • •artifacts/<ContractName>/<ContractName>.arc56.json — ARC-56 app spec
  • •artifacts/<ContractName>/client.ts — Generated TypeScript client

2. Deploy to Localnet

bash
# Start localnet if not running
algokit localnet start

# Deploy (runs deploy-config.ts)
algokit project deploy localnet

The deployment script (smart_contracts/deploy-config.ts) handles:

  • •Idempotent deployment (safe to re-run)
  • •App ID tracking
  • •Initial state setup

Note the App ID from the deployment output.

3. Interact Using Generated Client

Create scripts in your project to call contract methods. Example structure:

typescript
// scripts/call-contract.ts
import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import { CounterClient } from '../smart_contracts/artifacts/Counter/client'

async function main() {
  // Connect to localnet
  const algorand = AlgorandClient.fromEnvironment()

  // Get the default account (localnet dispenser)
  const deployer = await algorand.account.fromEnvironment('DEPLOYER')

  // Create client for deployed app
  const client = algorand.client.getTypedAppClientById(CounterClient, {
    appId: BigInt(1234), // Replace with actual App ID
    sender: deployer,
  })

  // Call a method
  const result = await client.send.increment({})
  console.log('New count:', result.return)

  // Read global state
  const state = await client.state.global.getAll()
  console.log('Global state:', state)
}

main().catch(console.error)

Run with:

bash
npx tsx scripts/call-contract.ts

4. Common Operations

Call a Method

typescript
// No arguments
const result = await client.send.increment({})

// With arguments
const result = await client.send.setValue({ args: { value: 42n } })

// Access return value
console.log('Return:', result.return)

Read Global State

typescript
// Get all global state
const state = await client.state.global.getAll()

// Get specific key (if typed in contract)
const count = await client.state.global.count()

Read Local State

typescript
// Get local state for an address
const localState = await client.state.local(address).getAll()

Opt-In to Application

typescript
// If contract has an opt_in method
await client.send.optIn.optIn({})

// Or use bare opt-in
await client.send.optIn.bare({})

Read Box Storage

typescript
// If contract uses boxes
const boxValue = await client.state.box.myBox()

Bulk Opt-In/Opt-Out

For batch operations across multiple assets:

typescript
// Bulk opt-in to multiple assets
const group = algorand.newGroup()
for (const assetId of assetIds) {
  group.addAssetOptIn({ sender: account.addr, assetId })
}
await group.send()

// Bulk opt-out from multiple assets
const closeGroup = algorand.newGroup()
for (const assetId of assetIds) {
  closeGroup.addAssetOptOut({ sender: account.addr, assetId, creator: creatorAddr })
}
await closeGroup.send()

Important Rules / Guidelines

  • •Always build before deploying: Run algokit project run build to generate fresh artifacts
  • •Use generated clients: They provide type safety and handle ABI encoding
  • •Check App ID: Get it from deployment output, don't hardcode across environments
  • •Use environment variables: Store sensitive data like mnemonics in .env
  • •Localnet accounts: Use algorand.account.fromEnvironment('DEPLOYER') for localnet

Common Variations / Edge Cases

ScenarioApproach
Deploy to testnetalgokit project deploy testnet (requires funded account)
Custom senderCreate account with algorand.account.fromMnemonic()
Multiple contractsCreate separate client instances for each
State not foundEnsure app is deployed and App ID is correct
Method not foundRebuild contract and regenerate client

Environment Setup

For non-localnet deployments, set environment variables:

bash
# .env file
ALGORAND_NETWORK=testnet
DEPLOYER_MNEMONIC="your twenty four word mnemonic phrase here"

References / Further Reading