@settlemint/sdk-eas 2.3.5-prea6b8850 → 2.3.5-prf7f294ed

package/README.md

@@ -1,187 +1,389 @@
-<p align="center">
-  <img src="https://github.com/settlemint/sdk/blob/main/logo.svg" width="200px" align="center" alt="SettleMint logo" />
-  <h1 align="center">SettleMint SDK</h1>
-  <p align="center">
-    ✨ <a href="https://settlemint.com">https://settlemint.com</a> ✨
-    <br/>
-    Integrate SettleMint into your application with ease.
-  </p>
-</p>
-
-<p align="center">
-<a href="https://github.com/settlemint/sdk/actions?query=branch%3Amain"><img src="https://github.com/settlemint/sdk/actions/workflows/build.yml/badge.svg?event=push&branch=main" alt="CI status" /></a>
-<a href="https://fsl.software" rel="nofollow"><img src="https://img.shields.io/npm/l/@settlemint/sdk-eas" alt="License"></a>
-<a href="https://www.npmjs.com/package/@settlemint/sdk-eas" rel="nofollow"><img src="https://img.shields.io/npm/dw/@settlemint/sdk-eas" alt="npm"></a>
-<a href="https://github.com/settlemint/sdk" rel="nofollow"><img src="https://img.shields.io/github/stars/settlemint/sdk" alt="stars"></a>
-</p>
-
-<div align="center">
-  <a href="https://console.settlemint.com/documentation">Documentation</a>
-  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://www.npmjs.com/package/@settlemint/sdk-eas">NPM</a>
-  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://github.com/settlemint/sdk/issues">Issues</a>
-  <br />
-</div>
-
-## Table of Contents
-
-- [About](#about)
-- [API Reference](#api-reference)
-  - [Functions](#functions)
-    - [createEASClient()](#createeasclient)
-  - [Interfaces](#interfaces)
-    - [RegisterSchemaOptions](#registerschemaoptions)
-    - [SchemaField](#schemafield)
-  - [Type Aliases](#type-aliases)
-    - [ClientOptions](#clientoptions)
-  - [Variables](#variables)
-    - [ClientOptionsSchema](#clientoptionsschema)
-    - [EAS\_FIELD\_TYPES](#eas_field_types)
-- [Contributing](#contributing)
-- [License](#license)
-
-## About
-
-The SettleMint EAS SDK provides a lightweight wrapper for the Ethereum Attestation Service (EAS), enabling developers to easily create, manage, and verify attestations within their applications. It simplifies the process of working with EAS by handling contract interactions, schema management, and The Graph integration, while ensuring proper integration with the SettleMint platform. This allows developers to quickly implement document verification, identity attestation, and other EAS-based features without manual setup.
+# @settlemint/sdk-eas
+
+Ethereum Attestation Service (EAS) integration for SettleMint SDK with Portal GraphQL support.
+
+## Features
+
+- ✅ **Portal SDK Integration**: Full integration with SettleMint Portal GraphQL API
+- ✅ **Complete EAS Support**: All 14 EAS mutations and queries implemented
+- ✅ **Type Safety**: Full TypeScript support with proper type definitions
+- ✅ **Contract Deployment**: Deploy EAS contracts via Portal
+- ✅ **Schema Management**: Register and retrieve attestation schemas
+- ✅ **Attestation Operations**: Create, revoke, and query attestations
+- ✅ **Multi-Operations**: Support for batch attestations and revocations
+- ✅ **Validation**: Built-in attestation validation and timestamp queries
+
+## Installation
+
+```bash
+npm install @settlemint/sdk-eas
+# or
+yarn add @settlemint/sdk-eas
+# or
+bun add @settlemint/sdk-eas
+```
+
+## Quick Start
+
+```typescript
+import { createEASClient } from "@settlemint/sdk-eas";
+
+// Initialize EAS client with Portal credentials
+const client = createEASClient({
+  instance: "https://attestation-portal-ee231.gke-europe.settlemint.com/graphql",
+  accessToken: "sm_aat_your_access_token",
+  debug: true,
+});
+
+// Deploy EAS contracts (if needed)
+const deployment = await client.deploy();
+console.log("EAS deployed at:", deployment.easAddress);
+console.log("Schema Registry at:", deployment.schemaRegistryAddress);
+
+// Register a schema
+const schemaResult = await client.registerSchema({
+  fields: [
+    { name: "user", type: "address", description: "User's wallet address" },
+    { name: "score", type: "uint256", description: "Reputation score" },
+    { name: "verified", type: "bool", description: "Verification status" },
+  ],
+  resolver: "0x0000000000000000000000000000000000000000",
+  revocable: true,
+});
+
+// Create an attestation
+const attestationResult = await client.attest({
+  schema: schemaResult.hash,
+  data: {
+    recipient: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
+    expirationTime: BigInt(0),
+    revocable: true,
+    refUID: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    data: "0x", // Encoded attestation data
+    value: BigInt(0),
+  },
+});
+
+console.log("Attestation created:", attestationResult.hash);
+```
+
+## Portal GraphQL Integration
+
+This package integrates with SettleMint's Portal GraphQL API, providing access to all EAS operations:
+
+### Available Mutations
+
+- `EasSchemaRegistryRegister` - Register new schemas
+- `EasDeploymentAttest` - Create single attestation
+- `EasDeploymentAttestByDelegation` - Create delegated attestation
+- `EasDeploymentMultiAttest` - Create multiple attestations
+- `EasDeploymentMultiAttestByDelegation` - Create multiple delegated attestations
+- `EasDeploymentRevoke` - Revoke single attestation
+- `EasDeploymentRevokeByDelegation` - Revoke by delegation
+- `EasDeploymentMultiRevoke` - Revoke multiple attestations
+- `EasDeploymentMultiRevokeByDelegation` - Revoke multiple by delegation
+- `EasDeploymentRevokeOffchain` - Revoke offchain attestation
+- `EasDeploymentMultiRevokeOffchain` - Revoke multiple offchain
+- `EasDeploymentTimestamp` - Timestamp operation
+- `EasDeploymentMultiTimestamp` - Timestamp multiple operations
+- `EasDeploymentIncreaseNonce` - Increase nonce for delegations
+
+### Available Queries
+
+- Contract deployment status and addresses
+- Schema retrieval and validation
+- Attestation lookup and verification
+- Transaction monitoring and history
 
 ## API Reference
 
-### Functions
+### EASClient
 
-#### createEASClient()
+The main client class for interacting with EAS via Portal.
 
-> **createEASClient**(`options`): `object`
+#### Constructor Options
 
-Defined in: [sdk/eas/src/eas.ts:36](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/eas.ts#L36)
+```typescript
+interface EASClientOptions {
+  instance: string;                           // Portal GraphQL endpoint
+  accessToken: string;                        // Portal access token
+  easContractAddress?: Address;               // Optional: EAS contract address
+  schemaRegistryContractAddress?: Address;    // Optional: Schema registry address
+  debug?: boolean;                           // Optional: Enable debug logging
+}
+```
 
-Creates an EAS client for interacting with the Ethereum Attestation Service.
+#### Methods
 
-##### Parameters
+- `deploy()` - Deploy EAS contracts
+- `registerSchema(request)` - Register new schema
+- `attest(request)` - Create attestation
+- `multiAttest(requests)` - Create multiple attestations
+- `revoke(uid, value?)` - Revoke attestation
+- `getSchema(uid)` - Get schema by UID
+- `getSchemas(options?)` - Get all schemas (paginated)
+- `getAttestation(uid)` - Get attestation by UID
+- `getAttestations(options?)` - Get all attestations (paginated)
+- `isValidAttestation(uid)` - Check attestation validity
+- `getTimestamp()` - Get contract timestamp
+- `getOptions()` - Get client configuration
+- `getPortalClient()` - Get Portal client instance
+- `getContractAddresses()` - Get current contract addresses
 
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options` | \{ `accessToken`: `string`; `attestationAddress`: `string`; `chainId`: `string`; `chainName`: `string`; `rpcUrl`: `string`; `schemaRegistryAddress`: `string`; \} | Configuration options for the client |
-| `options.accessToken` | `string` | Access token for the RPC provider (must start with 'sm_aat_' or 'sm_pat_') |
-| `options.attestationAddress` | `string` | The address of the EAS Attestation contract |
-| `options.chainId` | `string` | The chain ID to connect to |
-| `options.chainName` | `string` | The name of the chain to connect to |
-| `options.rpcUrl` | `string` | The RPC URL to connect to (must be a valid URL) |
-| `options.schemaRegistryAddress` | `string` | The address of the EAS Schema Registry contract |
+## Examples
 
-##### Returns
+See the [examples](./examples/) directory for complete usage examples:
 
-`object`
+- `simple-eas-workflow.ts` - Complete EAS workflow demonstration
+- Real-world attestation scenarios
+- Schema design patterns
+- Multi-attestation operations
 
-An object containing the EAS client instance
+## Development Status
 
-| Name | Type | Defined in |
-| ------ | ------ | ------ |
-| `getSchema()` | (`uid`) => `Promise`\<`string`\> | [sdk/eas/src/eas.ts:96](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/eas.ts#L96) |
-| `registerSchema()` | (`options`) => `Promise`\<`string`\> | [sdk/eas/src/eas.ts:95](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/eas.ts#L95) |
+- ✅ **Portal Client Integration**: Complete
+- ✅ **GraphQL Operations**: All 14 EAS mutations implemented
+- ✅ **Type Safety**: Full TypeScript support
+- ✅ **Error Handling**: Comprehensive error handling
+- ✅ **Testing**: Complete test suite
+- ✅ **Documentation**: Full API documentation
+- 🔄 **Real Portal Access**: Requires valid EAS Portal access token
 
-##### Throws
+## Requirements
 
-Will throw an error if the options fail validation
+- Node.js 20+
+- Valid SettleMint Portal access token
+- Access to EAS Portal instance
 
-##### Example
+## License
+
+FSL-1.1-MIT
+
+# EAS Portal SDK
+
+A TypeScript SDK for interacting with Ethereum Attestation Service (EAS) via SettleMint Portal.
+
+## Features
+
+- **Portal Integration**: Direct integration with SettleMint Portal GraphQL API
+- **Type Safety**: Full TypeScript support with proper type definitions
+- **Contract Management**: Deploy or connect to existing EAS contracts
+- **Schema Management**: Register and retrieve attestation schemas
+- **Attestation Operations**: Create, retrieve, and validate attestations
+- **Configurable**: No hardcoded values - all addresses and references are configurable
 
-```ts
-import { createEASClient } from '@settlemint/sdk-eas';
+## Installation
+
+```bash
+npm install @settlemint/sdk-eas
+# or
+bun add @settlemint/sdk-eas
+```
+
+## Quick Start
+
+```typescript
+import { createEASClient, ZERO_ADDRESS, ZERO_BYTES32 } from "@settlemint/sdk-eas";
 
 const client = createEASClient({
-  schemaRegistryAddress: "0x1234567890123456789012345678901234567890",
-  attestationAddress: "0x1234567890123456789012345678901234567890",
-  accessToken: "your-access-token",
-  chainId: "1",
-  chainName: "Ethereum",
-  rpcUrl: "http://localhost:8545"
+  instance: "https://attestation-portal-ee231.gke-europe.settlemint.com/graphql",
+  accessToken: "your-portal-access-token",
+  debug: true,
 });
+
+// Deploy contracts
+const deployment = await client.deploy("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
+
+// Register schema
+const schema = await client.registerSchema({
+  fields: [
+    { name: "user", type: "address" },
+    { name: "score", type: "uint256" },
+  ],
+  resolver: ZERO_ADDRESS, // No resolver
+  revocable: true,
+}, "0x8ba1f109551bD432803012645Hac136c22C177ec");
+
+// Create attestation
+const attestation = await client.attest({
+  schema: schema.hash,
+  data: {
+    recipient: "0x9876543210987654321098765432109876543210",
+    expirationTime: BigInt(0), // No expiration
+    revocable: true,
+    refUID: ZERO_BYTES32, // No reference
+    data: "0x1234",
+    value: BigInt(0),
+  },
+}, "0x8ba1f109551bD432803012645Hac136c22C177ec");
 ```
 
-### Interfaces
+## Configuration Constants
 
-#### RegisterSchemaOptions
+The SDK provides configurable constants instead of hardcoded values:
 
-Defined in: [sdk/eas/src/types.ts:34](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L34)
+### Address Constants
 
-Options for registering a new schema in the EAS Schema Registry.
+```typescript
+import { ZERO_ADDRESS, ZERO_BYTES32 } from "@settlemint/sdk-eas";
 
-##### Properties
+// Use ZERO_ADDRESS for:
+ZERO_ADDRESS // "0x0000000000000000000000000000000000000000"
 
-| Property | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| <a id="fields"></a> `fields` | [`SchemaField`](#schemafield)[] | Array of fields that make up the schema | [sdk/eas/src/types.ts:36](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L36) |
-| <a id="resolveraddress"></a> `resolverAddress` | `string` | Address of the resolver contract that will handle attestations | [sdk/eas/src/types.ts:38](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L38) |
-| <a id="revocable"></a> `revocable` | `boolean` | Whether attestations using this schema can be revoked | [sdk/eas/src/types.ts:40](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L40) |
+// Use ZERO_BYTES32 for:
+ZERO_BYTES32 // "0x0000000000000000000000000000000000000000000000000000000000000000"
+```
 
-***
+### Configurable Parameters
 
-#### SchemaField
+#### 1. Forwarder Address (Contract Deployment)
 
-Defined in: [sdk/eas/src/types.ts:22](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L22)
+```typescript
+// Option 1: No meta-transaction forwarder (default)
+await client.deploy(deployerAddress); // Uses ZERO_ADDRESS
 
-Represents a single field in an EAS schema.
+// Option 2: Custom forwarder for meta-transactions
+await client.deploy(deployerAddress, "0x1234567890123456789012345678901234567890");
+```
 
-##### Properties
+#### 2. Resolver Address (Schema Registration)
+
+```typescript
+// Option 1: No resolver (most common)
+await client.registerSchema({
+  fields: [...],
+  resolver: ZERO_ADDRESS, // No custom validation
+  revocable: true,
+}, fromAddress);
+
+// Option 2: Custom resolver contract
+await client.registerSchema({
+  fields: [...],
+  resolver: "0x5678901234567890123456789012345678901234", // Custom validation
+  revocable: true,
+}, fromAddress);
+```
 
-| Property | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| <a id="description"></a> `description?` | `string` | Optional description of the field's purpose | [sdk/eas/src/types.ts:28](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L28) |
-| <a id="name"></a> `name` | `string` | The name of the field | [sdk/eas/src/types.ts:24](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L24) |
-| <a id="type"></a> `type` | `"string"` \| `"address"` \| `"bool"` \| `"bytes"` \| `"bytes32"` \| `"int8"` \| `"int256"` \| `"uint8"` \| `"uint256"` | The Solidity type of the field | [sdk/eas/src/types.ts:26](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L26) |
+#### 3. Reference UID (Attestation Creation)
+
+```typescript
+// Option 1: Standalone attestation (most common)
+await client.attest({
+  schema: schemaUID,
+  data: {
+    recipient: recipientAddress,
+    refUID: ZERO_BYTES32, // No reference to other attestations
+    // ... other fields
+  },
+}, fromAddress);
+
+// Option 2: Reference another attestation
+await client.attest({
+  schema: schemaUID,
+  data: {
+    recipient: recipientAddress,
+    refUID: "0x1234567890123456789012345678901234567890123456789012345678901234", // Links to parent
+    // ... other fields
+  },
+}, fromAddress);
+```
 
-### Type Aliases
+#### 4. Expiration Time
 
-#### ClientOptions
+```typescript
+// Option 1: No expiration (permanent)
+expirationTime: BigInt(0)
 
-> **ClientOptions** = `z.infer`\<*typeof* [`ClientOptionsSchema`](#clientoptionsschema)\>
+// Option 2: Expires in 24 hours
+expirationTime: BigInt(Math.floor(Date.now() / 1000) + 86400)
 
-Defined in: [sdk/eas/src/client-options.schema.ts:28](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/client-options.schema.ts#L28)
+// Option 3: Specific timestamp
+expirationTime: BigInt(1735689600) // January 1, 2025
+```
 
-Configuration options for creating an EAS client.
-Combines EAS-specific options with base Viem client options.
+#### 5. Value (ETH Amount)
 
-### Variables
+```typescript
+// Option 1: No ETH sent (most common)
+value: BigInt(0)
 
-#### ClientOptionsSchema
+// Option 2: Send ETH with attestation
+value: BigInt("1000000000000000000") // 1 ETH in wei
+```
 
-> `const` **ClientOptionsSchema**: `ZodObject`\<\{ `accessToken`: `ZodString`; `attestationAddress`: `ZodString`; `chainId`: `ZodString`; `chainName`: `ZodString`; `rpcUrl`: `ZodString`; `schemaRegistryAddress`: `ZodString`; \}, `$strip`\>
+## API Reference
 
-Defined in: [sdk/eas/src/client-options.schema.ts:9](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/client-options.schema.ts#L9)
+### Client Creation
 
-Schema for validating EAS client configuration options.
-Extends the base Viem client options with EAS-specific requirements.
+```typescript
+interface EASClientOptions {
+  instance: string;                           // Portal GraphQL endpoint
+  accessToken: string;                        // Portal access token
+  easContractAddress?: Address;               // Optional: existing EAS contract
+  schemaRegistryContractAddress?: Address;    // Optional: existing Schema Registry
+  debug?: boolean;                           // Optional: enable debug logging
+}
+```
 
-***
+### Contract Deployment
 
-#### EAS\_FIELD\_TYPES
+```typescript
+async deploy(
+  deployerAddress: Address,
+  forwarderAddress?: Address,  // Optional: defaults to ZERO_ADDRESS
+  gasLimit?: string           // Optional: defaults to "0x3d0900"
+): Promise<DeploymentResult>
+```
 
-> `const` **EAS\_FIELD\_TYPES**: `object`
+### Schema Registration
+
+```typescript
+interface SchemaRequest {
+  fields?: SchemaField[];     // Alternative to schema string
+  schema?: string;           // Alternative to fields
+  resolver: Address;         // Use ZERO_ADDRESS for no resolver
+  revocable: boolean;        // Whether attestations can be revoked
+}
+
+async registerSchema(
+  request: SchemaRequest,
+  fromAddress: Address,
+  gasLimit?: string
+): Promise<TransactionResult>
+```
 
-Defined in: [sdk/eas/src/types.ts:5](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L5)
+### Attestation Creation
+
+```typescript
+interface AttestationData {
+  recipient: Address;        // Who receives the attestation
+  expirationTime: bigint;   // Use 0 for no expiration
+  revocable: boolean;       // Whether this can be revoked
+  refUID: Hex;             // Use ZERO_BYTES32 for no reference
+  data: Hex;               // Encoded attestation data
+  value: bigint;           // ETH amount to send (usually 0)
+}
+
+async attest(
+  request: AttestationRequest,
+  fromAddress: Address,
+  gasLimit?: string
+): Promise<TransactionResult>
+```
 
-Supported field types for EAS schema fields.
-Maps to the Solidity types that can be used in EAS schemas.
+## Examples
 
-##### Type declaration
+See the [examples](./examples/) directory for complete workflows:
 
-| Name | Type | Default value | Defined in |
-| ------ | ------ | ------ | ------ |
-| <a id="address"></a> `address` | `"address"` | `"address"` | [sdk/eas/src/types.ts:7](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L7) |
-| <a id="bool"></a> `bool` | `"bool"` | `"bool"` | [sdk/eas/src/types.ts:8](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L8) |
-| <a id="bytes"></a> `bytes` | `"bytes"` | `"bytes"` | [sdk/eas/src/types.ts:9](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L9) |
-| <a id="bytes32"></a> `bytes32` | `"bytes32"` | `"bytes32"` | [sdk/eas/src/types.ts:10](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L10) |
-| <a id="int256"></a> `int256` | `"int256"` | `"int256"` | [sdk/eas/src/types.ts:12](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L12) |
-| <a id="int8"></a> `int8` | `"int8"` | `"int8"` | [sdk/eas/src/types.ts:14](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L14) |
-| <a id="string"></a> `string` | `"string"` | `"string"` | [sdk/eas/src/types.ts:6](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L6) |
-| <a id="uint256"></a> `uint256` | `"uint256"` | `"uint256"` | [sdk/eas/src/types.ts:11](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L11) |
-| <a id="uint8"></a> `uint8` | `"uint8"` | `"uint8"` | [sdk/eas/src/types.ts:13](https://github.com/settlemint/sdk/blob/v2.3.5/sdk/eas/src/types.ts#L13) |
+- [`simple-eas-workflow.ts`](./examples/simple-eas-workflow.ts) - Complete EAS workflow with configuration options
+- Configuration examples for different use cases
 
-## Contributing
+## Testing
 
-We welcome contributions from the community! Please check out our [Contributing](https://github.com/settlemint/sdk/blob/main/.github/CONTRIBUTING.md) guide to learn how you can help improve the SettleMint SDK through bug reports, feature requests, documentation updates, or code contributions.
+```bash
+bun test
+```
 
 ## License
 
-The SettleMint SDK is released under the [FSL Software License](https://fsl.software). See the [LICENSE](https://github.com/settlemint/sdk/blob/main/LICENSE) file for more details.
+MIT