evmauth
Version:
TypeScript SDK for interacting with EVMAuth smart contracts deployed to Ethereum, Radius, and other EVM-compatible networks.
250 lines (188 loc) • 7.35 kB
Markdown
# EVMAuth TypeScript SDK
A TypeScript SDK for interacting with [EVMAuth contracts](https://github.com/evmauth/evmauth-core) deployed to Ethereum, Radius, and other EVM-compatible networks.
## Features
- Full TypeScript support with comprehensive type definitions
- Complete coverage of all EVMAuth contract functions
- Support for read and write operations
- Event handling with typed callbacks
- Works with any EVM-compatible network (Ethereum, Radius, etc.)
- Supports both providers and signers
## Installation
```bash
npm install evmauth ethers
```
## Quick Start
```typescript
import { ethers } from 'ethers';
import { EVMAuth } from 'evmauth';
// Replace with your EVMAuth contract address
const contractAddress = '0x1234567890abcdef1234567890abcdef12345678';
// Connect to an EVM network provider
const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
// Create an SDK instance
const evmAuth = new EVMAuth(contractAddress, provider);
// Read token metadata
const tokenId = 1;
evmAuth.metadataOf(tokenId)
.then(metadata => console.log('Token Metadata:', metadata))
.catch(console.error);
// Connect with a signer for write operations
const privateKey = 'YOUR_PRIVATE_KEY';
const signer = new ethers.Wallet(privateKey, provider);
const evmAuthSigner = evmAuth.connect(signer);
// Purchase a token
evmAuthSigner.purchase('0xRECIPIENT', tokenId, 1, ethers.parseEther('0.1'))
.then(tx => console.log('Transaction hash:', tx.hash))
.catch(console.error);
```
## Core Functionality
### Initialization
```typescript
// With provider (read-only)
const provider = new ethers.JsonRpcProvider('https://rpc.example.com');
const evmAuth = new EVMAuth(contractAddress, provider);
// With signer (read & write)
const signer = new ethers.Wallet(privateKey, provider);
const evmAuthSigner = new EVMAuth(contractAddress, signer);
// Or connect a signer to an existing instance
const evmAuthSigner = evmAuth.connect(signer);
```
### Reading Token Data
```typescript
// Get token metadata
const metadata = await evmAuth.metadataOf(tokenId);
console.log(metadata);
// { id: 0n, active: true, burnable: true, transferable: false, price: 100000000000000000n, ttl: 2592000n }
// Check token status
const isActive = await evmAuth.active(tokenId);
const isBurnable = await evmAuth.burnable(tokenId);
const isTransferable = await evmAuth.transferable(tokenId);
const isForSale = await evmAuth.forSale(tokenId);
// Get token price and TTL
const price = await evmAuth.priceOf(tokenId);
const ttl = await evmAuth.ttlOf(tokenId);
const expiration = await evmAuth.expirationFor(tokenId);
// Get token balance
const balance = await evmAuth.balanceOf(accountAddress, tokenId);
// Get detailed balance including expiration
const balanceDetailsOf = await evmAuth.balanceDetailsOf(accountAddress, tokenId);
console.log(balanceDetailsOf);
// [{ balance: 1n, expiresAt: 1714583142n }]
```
### Token Operations
```typescript
// Mint tokens (requires TOKEN_MINTER_ROLE)
await evmAuth.issue(recipientAddress, tokenId, amount);
// Burn tokens (requires TOKEN_BURNER_ROLE)
await evmAuth.burn(accountAddress, tokenId, amount);
// Purchase tokens
await evmAuth.purchase(recipientAddress, tokenId, amount, price);
// Transfer tokens (if transferable)
await evmAuth.safeTransferFrom(fromAddress, toAddress, tokenId, amount);
```
### Role Management
```typescript
// Get role constants
const minterRole = await evmAuth.TOKEN_MINTER_ROLE();
const burnerRole = await evmAuth.TOKEN_BURNER_ROLE();
const managerRole = await evmAuth.TOKEN_MANAGER_ROLE();
const blacklistRole = await evmAuth.BLACKLIST_MANAGER_ROLE();
const financeRole = await evmAuth.FINANCE_MANAGER_ROLE();
const adminRole = await evmAuth.DEFAULT_ADMIN_ROLE();
// Check roles
const hasMinterRole = await evmAuth.hasRole(minterRole, accountAddress);
// Grant roles (requires admin role)
await evmAuth.grantRole(minterRole, accountAddress);
await evmAuth.grantRoles([minterRole, burnerRole], accountAddress);
// Revoke roles
await evmAuth.revokeRole(minterRole, accountAddress);
await evmAuth.revokeRoles([minterRole, burnerRole], accountAddress);
```
### Blacklist Management
```typescript
// Check if an account is blacklisted
const isBlacklisted = await evmAuth.isBlacklisted(accountAddress);
// Add to blacklist (requires BLACKLIST_MANAGER_ROLE)
await evmAuth.addToBlacklist(accountAddress);
await evmAuth.addBatchToBlacklist([address1, address2, address3]);
// Remove from blacklist
await evmAuth.removeFromBlacklist(accountAddress);
await evmAuth.removeBatchFromBlacklist([address1, address2, address3]);
```
### Event Handling
```typescript
// Listen for token transfers (ERC-1155 TransferSingle event)
const unsubscribe = evmAuth.onTransferSingle(
(event) => {
console.log('Transfer:', event);
},
fromFilter, // optional: filter by sender address (use zero address for token minting events)
toFilter, // optional: filter by receiver address (use zero address for token burning events)
);
// Listen for token purchases
const unsubscribe = evmAuth.onTokenPurchased(
(event) => {
console.log('Purchase:', event);
},
accountFilter, // optional: filter by purchaser wallet address
tokenIdFilter, // optional: filter by token ID
);
// Stop listening
unsubscribe();
```
## Advanced Usage
### Admin Functions
```typescript
// Get contract owner
const owner = await evmAuth.owner();
// Transfer ownership (two-step process)
await evmAuth.beginDefaultAdminTransfer(newAdminAddress);
// Later, as the new admin:
await evmAuth.acceptDefaultAdminTransfer();
// Get/set wallet for receiving funds
const wallet = await evmAuth.wallet();
await evmAuth.setWallet(newWalletAddress);
// Withdraw funds
await evmAuth.withdraw();
```
### Token Configuration
```typescript
// Update token metadata
await evmAuth.setMetadata(
tokenId,
true, // active
true, // burnable
false, // transferable
ethers.parseEther('0.1'), // price
60 * 60 * 24 * 30 // ttl: 30 days in seconds
);
// Update token price
await evmAuth.setPriceOf(tokenId, ethers.parseEther('0.2'));
await evmAuth.setPriceOfBatch([token1, token2], [price1, price2]);
// Update token TTL
await evmAuth.setTTL(tokenId, 60 * 60 * 24 * 7); // 7 days in seconds
// Update URI
await evmAuth.setURI('https://metadata.example.com/{id}.json');
```
## Error Handling
The SDK propagates errors from the underlying contract calls. Common errors include:
- `AccessControlUnauthorizedAccount`: The caller does not have the required role
- `ERC1155InsufficientBalance`: Insufficient balance for a transfer or burn operation
- `ERC1155InvalidReceiver`: The recipient cannot receive ERC1155 tokens
Example error handling:
```typescript
try {
await evmAuth.issue(recipientAddress, tokenId, amount);
console.log('Tokens minted successfully');
} catch (error) {
if (error.message.includes('AccessControlUnauthorizedAccount')) {
console.error('Error: You do not have the TOKEN_MINTER_ROLE');
} else {
console.error('Unexpected error:', error);
}
}
```
## License
The **EVMAuth** TypeScript SDK is released under the MIT License. See the [LICENSE](LICENSE) file for details.