Ethereum Attestation Service (EAS) SDK

Overview

The EAS SDK is a Python library for seamlessly interacting with the Ethereum Attestation Service (EAS), enabling developers to create, manage, and verify on-chain and off-chain attestations across multiple blockchain networks.

Features

🌐 Multi-chain support (Ethereum, Base, Sepolia, and more)
🔒 Secure environment and input validation
💡 Easy-to-use methods for creating attestations
📝 On-chain and off-chain attestation support
🚀 Batch attestation and revocation capabilities
🕒 Flexible timestamping functionality
🔄 Typed attestation data conversion from GraphQL to protobuf

Installation

Install the EAS SDK using pip:

pip install eas-sdk

Quick Start

Basic Initialization

from EAS import EAS

# Initialize EAS for a specific chain
eas = EAS.from_chain(
    chain='base-sepolia',
    private_key='YOUR_PRIVATE_KEY',
    from_account='YOUR_ETHEREUM_ADDRESS'
)

Creating an Attestation

# Register a schema first
schema_uid = eas.register_schema(
    schema="uint256 id,string name",
    network_name="base-sepolia"
)

# Create an attestation
result = eas.attest(
    schema_uid=schema_uid,
    recipient='0x1234...',
    data_values={
        'types': ['uint256', 'string'],
        'values': [42, 'John Doe']
    }
)

print(f"Attestation created: {result.tx_hash}")

Off-Chain Attestation

# Create an off-chain attestation
offchain_attestation = eas.attest_offchain({
    'schema': schema_uid,
    'recipient': '0x1234...',
    'data': b'Offchain data'
})

Batch Operations

# Batch attestation
eas.multi_attest([
    {
        'schema_uid': schema_uid,
        'attestations': [
            {
                'recipient': '0x1234...',
                'data': b'First attestation'
            },
            {
                'recipient': '0x5678...',
                'data': b'Second attestation'
            }
        ]
    }
])

# Batch revocation
eas.multi_revoke([
    {'uid': '0x...first_attestation_uid'},
    {'uid': '0x...second_attestation_uid'}
])

Command Line Interface (CLI)

The EAS SDK includes a comprehensive CLI tool eas-tools for interacting with EAS data directly from the command line.

Installation and Setup

After installing the SDK, the eas-tools command is automatically available:

pip install eas-sdk
eas-tools --help

CLI Overview

The CLI is organized into logical command groups:

eas-tools [global-options] <command-group> <command> [options]

Command Groups:

schema - Schema operations (view, generate code)
attestation - Attestation operations (view, decode)
query - Bulk search operations
revoke - Revocation operations
dev - Development tools

Global Options:

--network, -n - Network to use (mainnet, sepolia, base-sepolia, etc.)
--help - Show help information
--version - Show version

Schema Commands

View Schema Information:

# View schema details
eas-tools -n base-sepolia schema show 0x86ad448d1844cd6d7c13cf5d8effbc70a596af78bd0a01b747e2acb5f74c6d9b

# Output formats: eas (default), json, yaml
eas-tools schema show 0x86ad... --format json

Generate Code from Schema:

# Generate TypeScript/protobuf definitions
eas-tools schema generate 0x86ad... --format proto

Attestation Commands

View Attestation Information:

# View attestation details
eas-tools -n base-sepolia attestation show 0xceffa19c412727fa6ea41ce8f685a397d93d744c5314f19c39fa7b007a985c41

# Output formats: eas (default), json, yaml  
eas-tools attestation show 0xceff... --format json

Decode Attestation Data:

# Parse attestation data using its schema
eas-tools attestation decode 0xceff19c412727fa6ea41ce8f685a397d93d744c5314f19c39fa7b007a985c41

# Advanced decoding options
eas-tools attestation decode 0xceff... --format proto --encoding protobuf

Query Commands

The query system provides powerful filtering capabilities for bulk data retrieval.

Search Attestations:

# Find all attestations for a schema
eas-tools -n base-sepolia query attestations --schema 0x86ad...

# Find attestations by attester/sender
eas-tools query attestations --sender 0x0E9A64...
eas-tools query attestations --attester 0x0E9A64...  # same as --sender

# Find attestations for a recipient  
eas-tools query attestations --recipient 0x742D35...

# Filter by status
eas-tools query attestations --active          # non-revoked attestations
eas-tools query attestations --revoked         # revoked attestations
eas-tools query attestations --revocable       # revocable attestations
eas-tools query attestations --expired         # expired attestations

# Time-based filtering (Unix timestamps)
eas-tools query attestations --expires-before 1735689600
eas-tools query attestations --expires-after 1735689600
eas-tools query attestations --created-after 1726147200

# Combine filters
eas-tools query attestations --sender 0x0E9A64... --active --revocable

# Pagination and output
eas-tools query attestations --limit 50 --offset 100 --format json

Search Schemas:

# Find schemas by creator
eas-tools query schemas --creator 0x1234...

# Filter by properties
eas-tools query schemas --revocable
eas-tools query schemas --resolvable       # schemas with resolver contracts

# Time-based filtering
eas-tools query schemas --created-after 1726147200

# Output options
eas-tools query schemas --format json --limit 25

Revocation Commands

The revoke command allows you to revoke attestations directly from the CLI.

Basic Revocation:

# Revoke using environment variables for credentials
export EAS_PRIVATE_KEY=0x1234...
export EAS_CHAIN=base-sepolia
eas-tools revoke 0xceff19c412727fa6ea41ce8f685a397d93d744c5314f19c39fa7b007a985c41

# Revoke using command line options
eas-tools -n base-sepolia revoke 0xceff... --private-key 0x1234...

# Dry run to preview transaction
eas-tools revoke 0xceff... --dry-run

Environment Variables for Revocation:

export EAS_PRIVATE_KEY=your_private_key
export EAS_FROM_ACCOUNT=your_address  # optional, derived from private key
export EAS_CHAIN=base-sepolia

Error Handling: The CLI provides user-friendly error messages for common contract errors:

"The attestation has already been revoked"
"Access denied - you don't have permission to revoke this attestation"
"Invalid attestation - the attestation UID doesn't exist or is malformed"
"This attestation is not revocable"

Development Commands

List Supported Networks:

# Show all supported networks
eas-tools dev chains

# Filter by network type
eas-tools dev chains --mainnet
eas-tools dev chains --testnet

Development Environment:

# Set up development environment
eas-tools dev setup

# Interactive Python shell with EAS SDK
eas-tools dev shell

# Run tests
eas-tools dev test

Real-World Examples

Find and Revoke Your Own Attestations:

# 1. Find your active attestations
eas-tools -n base-sepolia query attestations --sender 0xYourAddress... --active --format json

# 2. Revoke a specific attestation
eas-tools -n base-sepolia revoke 0xAttestationUID... --private-key 0xYourKey...

Analyze a Schema:

# 1. View schema structure
eas-tools schema show 0xSchemaUID... --format yaml

# 2. Find all attestations using this schema
eas-tools query attestations --schema 0xSchemaUID... --format json

# 3. Generate code definitions
eas-tools schema generate 0xSchemaUID... --format proto

Monitor Attestation Activity:

# Find recent attestations (last 24 hours)
YESTERDAY=$(date -d '1 day ago' +%s)
eas-tools query attestations --created-after $YESTERDAY --format table

# Find expiring attestations (next 30 days)  
MONTH_FROM_NOW=$(date -d '30 days' +%s)
eas-tools query attestations --expires-before $MONTH_FROM_NOW --format json

Network Support

The CLI supports all EAS networks:

mainnet - Ethereum Mainnet
sepolia - Ethereum Sepolia Testnet
base - Base Mainnet
base-sepolia - Base Sepolia Testnet
optimism - Optimism Mainnet
arbitrum - Arbitrum One
polygon - Polygon Mainnet

Use the --network or -n flag with any command:

eas-tools -n mainnet query attestations --sender 0x...
eas-tools -n base-sepolia revoke 0x...

Configuration

Environment Variables

You can also configure EAS using environment variables:

export EAS_CHAIN=base-sepolia
export EAS_PRIVATE_KEY=your_private_key
export EAS_FROM_ACCOUNT=your_ethereum_address

Then initialize EAS without parameters:

eas = EAS.from_environment()

Advanced Configuration

Custom Network Support

# Use a custom RPC endpoint and contract address
eas = EAS.from_chain(
    chain='custom_network',
    private_key='your_private_key',
    from_account='your_address',
    rpc_url='https://custom-rpc.network',
    contract_address='0x..custom_contract_address'
)

Supported Chains

# List all supported chains
print(EAS.list_supported_chains())

# Get configuration for a specific chain
base_config = EAS.get_network_config('base')

Security Features

Input validation for all parameters
Secure environment variable handling
Comprehensive error logging
Contract address validation

Attestation Data Conversion

Convert EAS attestation data from GraphQL responses to strongly-typed protobuf messages:

from src.main.EAS.attestation_converter import AttestationConverter, from_graphql_json

# Convert GraphQL decodedDataJson to typed objects
converter = AttestationConverter(
    lambda data: YourProtobufType(
        domain=data.get("domain", ""),
        identifier=data.get("identifier", "")
    )
)

graphql_data = from_graphql_json('your_decoded_data_json')
typed_result = converter.convert(graphql_data)

For detailed usage examples and advanced patterns, see Attestation Converter Documentation.

Error Handling

The SDK provides detailed exceptions:

EASValidationError: Input validation failures
EASTransactionError: Blockchain interaction problems
SecurityError: Security-related issues

Performance Considerations

Uses gas estimation with a 20% buffer
Supports batch operations for gas efficiency
Provides fallback mechanisms for gas estimation

Contribution

Contributions are welcome! Please read our Contribution Guidelines before submitting a pull request.

License

[Insert your project's license here]

Support

For issues, questions, or support, please file an issue on our GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github		.github
docs		docs
examples		examples
src		src
.flake8		.flake8
.gitignore		.gitignore
INTEGRATION.md		INTEGRATION.md
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
buf.gen.yaml		buf.gen.yaml
buf.yaml		buf.yaml
env.example		env.example
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Ethereum Attestation Service (EAS) SDK

Overview

Features

Installation

Quick Start

Basic Initialization

Creating an Attestation

Off-Chain Attestation

Batch Operations

Command Line Interface (CLI)

Installation and Setup

CLI Overview

Schema Commands

Attestation Commands

Query Commands

Revocation Commands

Development Commands

Real-World Examples

Network Support

Configuration

Environment Variables

Advanced Configuration

Custom Network Support

Supported Chains

Security Features

Attestation Data Conversion

Error Handling

Performance Considerations

Contribution

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages