WES Smart Contract SDK for JavaScript/TypeScript

__          ________ _____  _______     ___   _ 
\ \        / /  ____|_   _|/ ____\ \   / / \ | |
 \ \  /\  / /| |__    | | | (___  \ \_/ /|  \| |
  \ \/  \/ / |  __|   | |  \___ \  \   / | . ` |
   \  /\  /  | |____ _| |_ ____) |  | |  | |\  |
    \/  \/   |______|_____|_____/   |_|  |_| \_|

WES 区块链智能合约开发工具包 - JavaScript/TypeScript 版本
为智能合约开发者提供业务语义优先的合约开发能力

🚀 快速开始 • 🎨 合约模板 • 💡 核心能力 • 🏗️ 架构概览 • 📚 文档导航

---

🌟 它能帮你做什么？

在传统区块链开发中，开发者需要：

• ❌ 理解底层协议细节（UTXO、交易构建、签名等）
• ❌ 手动构建交易（选择输入、创建输出、计算手续费）
• ❌ 处理复杂的业务逻辑组合（转账、授权、质押等）

WES 智能合约 SDK 让这一切成为过去：

• ✅ 业务语义优先 - 提供 Transfer()、Mint()、Stake() 等直观的业务接口
• ✅ TypeScript/AssemblyScript - 使用熟悉的语言编写合约
• ✅ WASM 优化 - 专为 AssemblyScript WASM 编译优化，合约体积小、执行快
• ✅ 企业级能力 - 支持外部系统集成、长事务、复杂业务逻辑
• ✅ 类型安全 - 完整的类型定义和编译期检查，减少运行时错误

---

🚀 快速开始

前置要求

• Node.js 20+ - 用于开发环境
• TypeScript 5.0+ - 用于类型检查
• AssemblyScript 0.27+ - 用于编译到 WASM

# 安装 AssemblyScript
npm install -g assemblyscript

# 验证安装
asc --version

安装 SDK

npm install @weisyn/contract-sdk-js

在 package.json 中：

{
  "dependencies": {
    "@weisyn/contract-sdk-js": "^1.0.0"
  }
}

第一个合约

创建 hello.ts:

import { Contract, Context, ErrorCode } from '@weisyn/contract-sdk-js/as';

@contract('HelloWorld')
export class HelloWorldContract extends Contract {
  onInit(params: Uint8Array): ErrorCode {
    return ErrorCode.SUCCESS;
  }
  
  @call('SayHello')
  sayHello(): ErrorCode {
    const caller = Context.getCaller();
    const message = `Hello, ${caller}`;
    this.emitEvent('Greeting', String.UTF8.encode(message));
    this.setReturnData(String.UTF8.encode(message));
    return ErrorCode.SUCCESS;
  }
}

使用业务语义接口

推荐方式：使用 helpers 层的业务语义接口：

import { Token } from '@weisyn/contract-sdk-js/helpers';
import { Context, ErrorCode } from '@weisyn/contract-sdk-js/as';

@call('Transfer')
transfer(): ErrorCode {
  const params = Context.getContractParams();
  const toStr = params.parseJSON('to');
  const amount = params.parseJSONInt('amount');
  
  const to = Context.parseAddressBase58(toStr);
  if (to === null) {
    return ErrorCode.ERROR_INVALID_PARAMS;
  }
  
  const caller = Context.getCaller();
  const result = Token.transfer(caller, to, amount, null);
  if (result !== ErrorCode.SUCCESS) {
    return ErrorCode.ERROR_EXECUTION_FAILED;
  }
  
  return ErrorCode.SUCCESS;
}

编译合约

# 使用 AssemblyScript 编译器
asc hello.ts --target release --outFile hello.wasm

📖 完整指南：开发者指南 | 合约模板

---

🎨 合约模板

contract-sdk-js 内置了大量按业务场景分类的合约模板，帮助你在统一的业务语义与最佳实践下快速落地：

• 学习模板 (templates/learning/)
  • hello-world：最小可运行合约，熟悉调用入口、返回码与事件
  • simple-token：基础可转账代币，实现 Transfer 等常见操作
  • basic-nft：简单 NFT 发行与转移
• 标准业务模板 (templates/standard/)
  • token/：多种代币形态（可分/不可分、白名单、权限控制等）
  • staking/：质押、解押、收益分配等 Staking 场景
  • governance/：提案、投票、治理流程模板
  • market/：托管、分阶段释放（vesting）、撮合等市场场景
  • nft/：多种 NFT 发行、拍卖、交易场景
  • rwa/：实物资产上链与代币化模板
  • defi/：AMM、借贷、流动性池等 DeFi 场景

如何使用模板（通用步骤）：

1. 进入目标模板目录，例如：

   cd templates/learning/simple-token

2. 阅读当前目录下的 README.md，根据说明完成依赖安装与环境准备

3. 根据模板提供的构建脚本或文档使用 AssemblyScript 编译为 WASM

4. 在 WES Workbench（如 contract-workbench 或 model-workbench）中导入生成的 WASM 与 metadata.json 完成部署与测试

📖 模板总览与场景说明：详见 模板中心
📌 模板对齐：TS/AS 模板与 Go 模板在业务场景上一一对应，保证同一业务场景下行为一致

---

💡 核心能力

1. 🎯 业务语义接口

SDK 提供丰富的业务语义接口，让开发者专注于业务逻辑：

模块	功能	示例
Token	转账、铸造、销毁、授权、冻结、空投	Token.transfer(from, to, amount, tokenID)
NFT	铸造、转移、销毁、查询所有者	NFT.mint(to, tokenID, metadata)
Staking	质押、解质押、委托、取消委托	Staking.stake(staker, validator, amount)
Governance	提案、投票、投票统计	Governance.vote(voter, proposalID, support)
Market	托管、分阶段释放	Market.escrow(buyer, seller, amount, escrowID)
RWA	资产验证、估值、代币化	RWA.validateAndTokenize(...)
External	外部 API 调用、数据库查询	External.callAPI(url, method, params)

2. 🔮 ISPC 创新：受控外部交互

传统区块链：需要中心化的预言机服务获取外部数据
WES ISPC：合约可以直接调用外部 API，无需传统预言机

import { External } from '@weisyn/contract-sdk-js/helpers';

// 直接调用外部 API（受控机制，替代传统预言机）
const data = External.callAPI(
  'https://api.example.com/price',
  'GET',
  JSON.stringify({ symbol: 'BTC' }),
  evidence  // API 数字签名和响应哈希（佐证）
);
// ✅ 单次调用，多点验证，自动生成 ZK 证明

3. 🏢 企业级能力

• 原子性长事务：跨系统业务流程在一个原子边界内执行
• 外部系统集成：直接调用外部 API、查询数据库
• 复杂业务逻辑：支持完整的业务执行流程

---

🏗️ 架构概览

📖 完整架构文档：详见 架构设计文档 | 架构规划文档

在 WES 7 层架构中的位置

contract-sdk-js 位于 WES 系统的应用层 & 开发者生态中的 SDK 工具链，用于开发运行在 ISPC 执行层的智能合约：

graph TB
    subgraph DEV_ECOSYSTEM["🎨 应用层 & 开发者生态"]
        direction TB
        subgraph SDK_LAYER["SDK 工具链"]
            direction LR
            CLIENT_SDK["Client SDK<br/>Go/JS/Python/Java<br/>📱 DApp·钱包·浏览器<br/>链外应用开发"]
            CONTRACT_SDK["Contract SDK (WASM)<br/>TypeScript/AssemblyScript<br/>📜 智能合约开发<br/>⭐ contract-sdk-js<br/>链上合约开发"]
            AI_SDK["AI SDK (ONNX)"]
        end
        subgraph END_USER_APPS["终端应用"]
            direction LR
            WALLET_APP["Wallet<br/>钱包应用"]
            EXPLORER["Explorer<br/>区块浏览器"]
            DAPP["DApp<br/>去中心化应用"]
        end
    end
    
    subgraph API_GATEWAY["🌐 API 网关层"]
        direction LR
        JSONRPC["JSON-RPC 2.0<br/>:8545"]
        HTTP["HTTP REST<br/>/api/v1/*"]
    end
    
    subgraph ISPC_LAYER["🔮 ISPC 执行层"]
        direction LR
        WASM_ENGINE["WASM 引擎<br/>合约执行环境"]
        HOSTABI["HostABI<br/>17个原语"]
    end
    
    subgraph BIZ_LAYER["💼 业务服务层"]
        APP_SVC["App Service<br/>应用编排·生命周期"]
    end
    
    WALLET_APP --> CLIENT_SDK
    EXPLORER --> CLIENT_SDK
    DAPP --> CLIENT_SDK
    
    CLIENT_SDK --> JSONRPC
    CLIENT_SDK --> HTTP
    
    JSONRPC --> APP_SVC
    HTTP --> APP_SVC
    
    CONTRACT_SDK -.编译为WASM.-> WASM_ENGINE
    WASM_ENGINE --> HOSTABI
    HOSTABI --> APP_SVC
    
    style CONTRACT_SDK fill:#81C784,color:#fff,stroke:#4CAF50,stroke-width:3px
    style ISPC_LAYER fill:#9C27B0,color:#fff
    style API_GATEWAY fill:#64B5F6,color:#fff
    style BIZ_LAYER fill:#FFB74D,color:#333

Loading

📖 完整 WES 架构：详见 WES 系统架构文档
📱 Client SDK：用于链外应用开发，详见 Client SDK (JS)

SDK 内部分层架构

SDK 采用分层架构，合约开发者只需使用业务语义层：

graph TB
    subgraph CONTRACT_DEV["👨‍💻 合约开发者（TS/AS）"]
        direction LR
        CONTRACT_CODE["合约代码<br/>使用 helpers API"]
    end
    
    subgraph HELPERS_LAYER["业务语义层 (helpers/)"]
        direction LR
        TOKEN["Token<br/>转账·铸造·销毁"]
        NFT["NFT<br/>铸造·转移"]
        STAKING["Staking<br/>质押·委托"]
        GOVERNANCE["Governance<br/>提案·投票"]
        MARKET["Market<br/>托管·释放"]
        RWA["RWA<br/>资产代币化"]
        EXTERNAL["External<br/>外部API调用"]
    end
    
    subgraph FRAMEWORK_LAYER["框架层 (framework/)"]
        direction TB
        CONTRACT["Contract 基类"]
        CONTEXT["Context<br/>上下文"]
        STORAGE["Storage<br/>状态管理"]
        TX_BUILDER["TransactionBuilder<br/>交易构建"]
    end
    
    subgraph RUNTIME_LAYER["运行时层 (runtime/)"]
        direction TB
        HOSTABI_WRAP["HostABI 绑定<br/>17个原语"]
        MEMORY["Memory 管理"]
        ENV["环境变量"]
    end
    
    subgraph WES_PROTOCOL["WES 协议层"]
        direction TB
        EUTXO["EUTXO 交易模型"]
        ISPC["可验证计算 (ISPC)"]
        URES["统一资源管理 (URES)"]
    end
    
    CONTRACT_DEV --> HELPERS_LAYER
    HELPERS_LAYER --> FRAMEWORK_LAYER
    FRAMEWORK_LAYER --> RUNTIME_LAYER
    RUNTIME_LAYER --> WES_PROTOCOL
    
    style CONTRACT_DEV fill:#E3F2FD
    style HELPERS_LAYER fill:#4CAF50,color:#fff
    style FRAMEWORK_LAYER fill:#2196F3,color:#fff
    style RUNTIME_LAYER fill:#FF9800,color:#fff
    style WES_PROTOCOL fill:#9C27B0,color:#fff

Loading

关键原则：

• ✅ 合约开发者：只使用 helpers 层的业务语义接口
• ✅ SDK 职责：自动处理底层协议细节（交易构建、状态管理等）
• ❌ 不需要了解：底层协议实现细节

---

📖 文档导航

🎯 按角色导航

👨‍💻 合约开发者

• 快速开始 → 开发者指南 → 合约模板

🏗️ 架构师/贡献者

• 架构概览 → 文档中心 → 架构设计文档

📚 深入理解

• API 参考 → 业务场景实现指南

📘 核心文档

文档	说明	受众
⭐ 主 README	SDK 总览和快速开始	所有用户
📖 文档中心	完整文档索引和导航	所有用户
🚀 开发者指南	如何使用 TS/AS SDK 开发合约	合约开发者
📚 API 参考	TS/AS SDK 接口详细说明	合约开发者
🎯 业务场景实现指南	如何实现业务场景	合约开发者
🏗️ 架构设计文档	SDK 架构设计讨论	架构师/贡献者
⚠️ 语言与 WASM 限制	TypeScript/AssemblyScript 限制和最佳实践	合约开发者

🔗 模块文档

• 合约模板 - SDK 提供的合约开发模板
• Helpers 层文档 - 业务语义层详细说明（规划中）
• Framework 层文档 - 框架层详细说明（规划中）

📖 完整文档导航：文档中心

---

🆚 与其他 SDK 的对比

特性	传统 SDK	WES SDK
API 设计	底层原语（TxAddInput 等）	业务语义（Transfer、Mint 等）
外部集成	需要预言机（中心化瓶颈）	原生支持（受控机制）
复杂业务	难以实现长事务	支持原子性长事务
类型安全	部分支持	完整类型系统（TypeScript/AssemblyScript）
学习曲线	需要了解底层协议	直观的业务接口

Go SDK vs TS/AS SDK

维度	Go SDK	TS/AS SDK
语言	Go/TinyGo	TypeScript/AssemblyScript
编译工具	TinyGo	AssemblyScript
业务语义	✅ 一致	✅ 一致
模板对齐	✅ 业务场景一致	✅ 业务场景一致
API 风格	Go 风格	TS/AS 风格

📖 能力对比：详见 应用场景分析

---

🤝 贡献指南

我们欢迎社区贡献！查看 贡献指南 了解详情。

# 设置开发环境
npm install
npm run build

# 运行测试
npm test

# 提交变更
git commit -S -m "feat: your contribution"
git push origin your-branch

---

📄 许可证

本项目基于 Apache-2.0 许可证开源 - 详见 LICENSE 文件。

---

🔗 相关链接

平台文档（高层次视图）

• 智能合约平台文档 - 智能合约平台的综合文档
  • 市场价值 - 市场价值和商业潜力
  • 产品设计 - 产品特性和用户体验（包含 SDK 设计）
  • 技术架构 - 技术实现架构
  • 应用场景 - 实际应用案例（包含 SDK 示例）
  • 快速开始 - 开发者快速入门

技术实现文档

• ISPC 组件文档 - ISPC 核心范式和实现细节
• WASM 引擎文档 - WASM 执行引擎架构
• HostABI 文档 - HostABI 17个原语设计

开发实践文档

• 合约开发平台 - 模板库、工具链、系统合约
• 合约教程 - 合约开发教程

其他链接

• WES 主项目 - WES 区块链主仓库
• WES 文档中心 - 完整技术文档
• WES 系统架构 - 系统架构详解
• Contract SDK (Go) - Go 合约 SDK

---

让智能合约开发回归业务本质

立即开始 • 查看文档 • 使用模板

Made with ❤️ by the WES Team

---

最后更新: 2025-11-23