# java-executor-avm
**Repository Path**: chenhonghua/java-executor-avm
## Basic Information
- **Project Name**: java-executor-avm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Java Executor AVM
Java Executor AVM 是一个基于 [Aion 虚拟机](https://github.com/aionnetwork/AVM.git) 的动态代码执行框架，支持在运行时动态编译和执行 Java 代码块。该项目类似于 Janino Executor，但使用了 AVM 作为底层执行引擎，提供了更高的安全性和隔离性。
## 项目特性
- **动态编译**: 支持运行时动态编译 Java 源代码
- **沙箱执行**: 使用 AVM 提供安全的代码执行环境
- **合约管理**: 支持智能合约的创建、部署和调用
- **导入控制**: 提供可配置的 import 白名单机制
- **能量管理**: 支持执行能量限制和管理
## 技术栈
- **Java 版本**: Java 21
- **构建工具**: Maven
- **核心依赖**:
- ASM 9.9.1 (字节码操作)
- Aion AVM (Aion 虚拟机)
- EdDSA 0.3.0 (加密库)
- SpongyCastle 1.58.0.0 (密码学库)
## 项目结构
```
java-executor-avm/
├── src/main/java/
│ ├── com/synctech/executor/avm/ # 核心执行器模块
│ │ ├── Executor.java # 代码执行器
│ │ ├── Manager.java # 管理器（合约注册和管理）
│ │ ├── CodeDefinition.java # 代码定义和编译器
│ │ ├── ByteArrayClassLoader.java # 字节数组类加载器
│ │ └── Constant.java # 常量定义
│ ├── org/aion/ # Aion AVM 核心库
│ ├── p/avm/ # AVM API 封装
│ ├── s/java/ # Shadow Java 类库
│ └── i/ # 接口和工具类
└── src/test/ # 测试代码
```
## 快速开始
### 1. 环境要求
- JDK 21 或更高版本
- Maven 3.6+
### 2. 安装依赖
```bash
mvn clean install
```
### 3. 基本使用示例
#### 添加合约
```java
import com.synctech.executor.avm.Manager;
// 注册一个合约
String creatorAddress = "0x1234567890abcdef..."; // 创建者地址（32 字节 hex）
String contractAddress = "0xfedcba0987654321..."; // 合约地址（32 字节 hex）
String code = "..."; // Java 源代码
Manager.add(creatorAddress, contractAddress, code);
```
#### 执行合约
```java
import com.synctech.executor.avm.Executor;
import org.aion.avm.core.FutureResult;
// 调用合约方法
FutureResult[] results = Executor.invoke(
senderAddress, // 发送者地址
contractAddress, // 合约地址
methodName, // 方法名
arg1, arg2, ... // 参数
);
```
## 核心组件说明
### Executor（执行器）
`Executor` 类提供代码执行的静态方法：
- `invoke(String senderAddress, String contractAddress, String methodName, Object... arguments)`
- 执行指定合约的方法
- 返回 `FutureResult[]` 结果数组
### Manager（管理器）
`Manager` 类负责合约的管理和 AVM 实例管理：
- `add(String creatorAddress, String contractAddress, String code)` - 添加合约
- `get(String contractAddress)` - 获取合约定义
- `clear()` - 清除所有合约
- `contains(String contractAddress)` - 检查合约是否存在
- `getAvmInstance()` - 获取 AVM 实例
### CodeDefinition（代码定义）
`CodeDefinition` 类处理代码的编译和打包：
- 自动将代码片段包装为完整的 Java 类
- 编译 Java 源代码为字节码
- 构建包含 Manifest 的 JAR 文件
- 生成 AVM 合约字节码
## 安全特性
### Import 白名单
项目通过 `Constant.ALLOWED_IMPORTS` 控制允许导入的包，防止不安全的代码访问。可以在 `Constant.java` 中配置允许的包前缀。
### 沙箱隔离
所有代码都在 AVM 沙箱中执行，与主机系统隔离，确保：
- 无法直接访问文件系统
- 无法访问网络资源
- 受限的内存使用
- 可控的执行能量
## 配置说明
### Maven 配置
在 `pom.xml` 中已配置以下关键设置：
```xml
21
UTF-8
9.9.1
```
### 编译配置
项目使用 Maven 编译插件，配置了 Java 21 源和目标版本：
```xml
org.apache.maven.plugins
maven-compiler-plugin
${java.version}
${java.version}
UTF-8
```
## 使用场景
1. **智能合约平台**: 部署和执行用户提交的智能合约
2. **规则引擎**: 动态加载业务规则并执行
3. **脚本引擎**: 支持用户自定义脚本逻辑
4. **插件系统**: 热插拔的插件架构
5. **代码评测系统**: 安全的代码提交和执行环境
## 注意事项
### 地址格式
所有地址必须为 32 字节的十六进制字符串，使用 `Helpers.hexStringToBytes()` 进行转换。
### 能量限制
默认执行能量限制为 5,000,000，可在调用时调整。
### 类加载
使用自定义的 `ByteArrayClassLoader` 加载动态编译的类，确保类的隔离性。
## 开发指南
### 编写合约代码
合约代码应为完整的 Java 类，例如：
```java
import org.aion.avm.userlib.*;
public class MyContract {
public static Object execute(Object[] args) {
// 业务逻辑
return result;
}
}
```
### 错误处理
执行失败时会抛出异常，建议捕获并处理：
```java
try {
FutureResult[] results = Executor.invoke(...);
// 处理结果
} catch (Exception e) {
// 处理异常
}
```
## 许可证
本项目基于 Aion AVM 构建，遵循相应的开源许可证。
## 贡献
欢迎提交 Issue 和 Pull Request！
## 联系方式
- 项目组织：Synctech
- 项目邮箱：（待补充）
- 问题反馈：（待补充）
---
**注意**: 这是一个技术预览版本，某些 API 可能会在未来版本中发生变化。在生产环境使用前，请充分测试和评估。