Antelope Dart

A Dart library for interacting with Antelope (EOSIO) powered blockchains.

This project is a port of the wharfkit/antelope TypeScript SDK to the Dart language.

Project Background & Status

This was an experimental attempt by the Greymass team to explore the Flutter/Dart ecosystem. Although this experiment is currently paused, we decided to open-source the codebase in hopes that it might be useful to other developers.

• Status: Basically Usable
• Testing: Includes a reasonable scale of unit tests covering core APIs and serialization logic.
• Disclaimer: While the code structure is complete and passes existing tests, this is an experimental project that is no longer actively maintained. If you plan to use this library in a production environment, please ensure you perform comprehensive testing and verification yourself.

Features

• Core Types: Full implementation of Antelope chain types (Name, Asset, Authority, etc.).
• Serialization: Robust ABI serialization and deserialization using code generation.
• APIs: Client implementations for Chain API and History API (v1).
• Transactions: Tools for creating, signing, and pushing transactions.
• Testing: Utilities for mocking blockchain responses.

Installation

Add the dependencies to your pubspec.yaml:

dependencies:
  antelope:
    path: ./path/to/antelope # or git dependency
  antelope_struct:
    path: ./path/to/antelope_struct

dev_dependencies:
  build_runner: ^2.4.0

Using AntelopeStruct for Code Generation

To handle the complex ABI serialization and deserialization in the Antelope protocol, this project uses a code generator. You don't need to manually write tedious toJson, toABI, or fromABI logic; simply define the struct and add annotations.

1. Define Data Structure

Create a Dart file (e.g., transfer.dart) and define your class following these steps:

1. Import necessary libraries.
2. Add the part 'filename.g.dart'; directive.
3. Mark the class with the @AntelopeStruct annotation, passing the struct name as defined in the ABI.
4. Extend ABISerializableStruct and mix in the generated Mixin.
5. Link static factory methods.

Example Code:

import 'package:antelope/src/chain/index.dart'; // Contains core types like Name, Asset
import 'package:antelope/src/serializer/serializable.dart';
import 'package:antelope_struct/antelope_struct.dart';

// Must add this line, the filename must match the current file
part 'transfer.g.dart';

@AntelopeStruct('transfer')
class Transfer extends ABISerializableStruct with _$TransferMixin {
  @override
  final Name from;

  @override
  final Name to;

  @override
  final Asset quantity;

  @override
  final ABIString memo; // Use ABIString for strings to support ABI serialization

  Transfer(this.from, this.to, this.quantity, this.memo);

  // Link the static factory methods generated by the generator
  // These are required for restoring objects from JSON or ABI binary data
  static final FromFactory fromData = _$TransferFrom;
  static final FromABIFactory fromABI = _$TransferFromABI;
}

2. Run Code Generator

After writing the struct, you need to run build_runner to generate the corresponding .g.dart file (containing serialization logic).

Run the following command in the project root:

dart run build_runner build --delete-conflicting-outputs

Or watch for file changes during development:

dart run build_runner watch --delete-conflicting-outputs

3. Use Generated Classes

Once the code is generated, you can use it like a normal Dart object, and it will have the ability to interact with the chain:

// Create object
final transfer = Transfer(
  Name.fromData('alice'),
  Name.fromData('bob'),
  Asset.fromData('1.0000 EOS'),
  ABIString('memo content')
);

// Serialize to ABI (Binary)
final encoder = ABIEncoder();
transfer.toABI(encoder);
final bytes = encoder.getData();

// Create from JSON (e.g., data returned from API)
final fromJson = Transfer.fromData({
  'from': 'alice',
  'to': 'bob',
  'quantity': '1.0000 EOS',
  'memo': 'memo content'
});

Running Tests

The project contains a series of unit tests that you can run to verify functionality:

dart test

For Mock tests involving network requests (record/replay mode), please refer to test/utils/mock_provider.dart.