Eco1155 TypeScript SDK

TypeScript SDK for interacting with the Eco1155 ERC-1155 upgradeable smart contract.

Installation

npm install eco-blockchain-sdk-ts

Development Setup

# Clone the repository
git clone https://github.com/yourusername/blockchain-smart-contract.git
cd packages/sdk-ts

# Install dependencies
npm install

# Build the SDK
npm run build

# Type check
npm run type-check

# Run tests
npm test

Usage

Basic Setup

import { Eco1155SDK } from 'eco-blockchain-sdk-ts';
import { ethers } from 'ethers';

// Connect to provider
const provider = new ethers.JsonRpcProvider('http://localhost:8545');
const signer = new ethers.Wallet(privateKey, provider);

// Initialize SDK
const sdk = new Eco1155SDK(contractAddress, signer);

Read Operations

// Get contract metadata
const name = await sdk.name();
const symbol = await sdk.symbol();
const owner = await sdk.owner();
const minter = await sdk.minter();

// Check balances
const balance = await sdk.balanceOf(address, tokenId);
const balances = await sdk.balanceOfBatch([address1, address2], [id1, id2]);

// Get URI
const uri = await sdk.uri(tokenId);

// Check if nonce is used
const messageHash = Eco1155SDK.createMessageHash(to, id, amount, nonce);
const isUsed = await sdk.isUsedNonce(messageHash);

Write Operations

// Mint single token (requires minter or owner role)
const tx = await sdk.mint(toAddress, tokenId, amount, '0x');
await tx.wait();

// Mint batch tokens (requires minter or owner role)
const tx = await sdk.mintBatch(
  toAddress, 
  [tokenId1, tokenId2], 
  [amount1, amount2], 
  '0x'
);
await tx.wait();

// Set minter (requires owner role)
const tx = await sdk.setMinter(newMinterAddress);
await tx.wait();

// Set URI (requires owner role)
const tx = await sdk.setURI('https://example.com/{id}.json');
await tx.wait();

Signature-based Minting

// Create signature for minting
const to = userAddress;
const id = 1;
const amount = 10;
const nonce = Date.now();

const signature = await Eco1155SDK.signMintMessage(
  signerWallet, 
  to, 
  id, 
  amount, 
  nonce
);

// Anyone can call this with a valid signature
const tx = await sdk.mintWithSignature(
  to, 
  id, 
  amount, 
  '0x', 
  nonce, 
  signature
);
await tx.wait();

Gas Estimation

// Estimate gas for operations
const mintGas = await sdk.estimateMintGas(to, id, amount, '0x');
const batchGas = await sdk.estimateMintBatchGas(to, [id1, id2], [amt1, amt2], '0x');
const sigGas = await sdk.estimateMintWithSignatureGas(to, id, amount, '0x', nonce, sig);
const minterGas = await sdk.estimateSetMinterGas(newMinter);
const uriGas = await sdk.estimateSetURIGas(newUri);

console.log(`Estimated gas: ${mintGas.toString()}`);

Event Listeners

// Listen for MinterSet events
const unsubscribe = sdk.onMinterSet((minter, event) => {
  console.log('New minter set:', minter);
  console.log('Block number:', event.blockNumber);
});

// Listen for TransferSingle events
const unsubTransfer = sdk.onTransferSingle((operator, from, to, id, value, event) => {
  console.log(`Transfer: ${value.toString()} of token ${id.toString()}`);
  console.log(`From: ${from} To: ${to}`);
});

// Listen for TransferBatch events
const unsubBatch = sdk.onTransferBatch((operator, from, to, ids, values, event) => {
  console.log('Batch transfer:', ids.length, 'tokens');
});

// Listen for URI changes
const unsubURI = sdk.onURI((value, id, event) => {
  console.log(`URI updated for token ${id.toString()}: ${value}`);
});

// Clean up listeners when done
unsubscribe();
unsubTransfer();
unsubBatch();
unsubURI();

// Or remove all listeners at once
sdk.removeAllListeners();

API Reference

Constructor

new Eco1155SDK(address: string, provider: ethers.Provider | ethers.Signer)

Read Methods

• owner(): Promise<string> - Get contract owner
• minter(): Promise<string> - Get authorized minter
• name(): Promise<string> - Get contract name
• symbol(): Promise<string> - Get contract symbol
• balanceOf(account: string, id: number): Promise<bigint> - Get token balance
• balanceOfBatch(accounts: string[], ids: number[]): Promise<bigint[]> - Get multiple balances
• uri(id: number): Promise<string> - Get token URI
• isUsedNonce(messageHash: string): Promise<boolean> - Check if nonce is used

Write Methods

• mint(to: string, id: number, amount: number, data: string): Promise<TransactionResponse>
• mintBatch(to: string, ids: number[], amounts: number[], data: string): Promise<TransactionResponse>
• mintWithSignature(to: string, id: number, amount: number, data: string, nonce: number, signature: string): Promise<TransactionResponse>
• setMinter(minter: string): Promise<TransactionResponse>
• setURI(newuri: string): Promise<TransactionResponse>

Gas Estimation Methods

• estimateMintGas(...): Promise<bigint>
• estimateMintBatchGas(...): Promise<bigint>
• estimateMintWithSignatureGas(...): Promise<bigint>
• estimateSetMinterGas(...): Promise<bigint>
• estimateSetURIGas(...): Promise<bigint>

Event Listener Methods

• onMinterSet(callback): () => void - Returns unsubscribe function
• onTransferSingle(callback): () => void
• onTransferBatch(callback): () => void
• onURI(callback): () => void
• removeAllListeners(): void

Static Helper Methods

• Eco1155SDK.createMessageHash(to: string, id: number, amount: number, nonce: number): string
• Eco1155SDK.signMintMessage(signer: ethers.Signer, to: string, id: number, amount: number, nonce: number): Promise<string>

Examples

See the test suite in ../test/src/eco1155.test.ts for comprehensive usage examples.

Publishing to npm

Prerequisites

1. Update the repository URLs in package.json:

   • repository.url - Your GitHub repository URL
   • homepage - Link to the sdk-ts directory
   • bugs.url - Issues URL

2. Create an npm account at npmjs.com

3. Login to npm:

   npm login

Publishing Steps

1. Validate the package:

   # Windows
   .\validate-publish.ps1
      
   # macOS/Linux
   ./validate-publish.sh

2. Build the SDK:

   npm run build

3. Test publication (dry-run):

   npm publish --dry-run

   This will show what files will be published without actually publishing.

4. Update version number (if necessary):

   npm version patch   # for bug fixes (1.0.0 -> 1.0.1)
   npm version minor   # for new features (1.0.0 -> 1.1.0)
   npm version major   # for breaking changes (1.0.0 -> 2.0.0)

5. Publish to npm:

   npm publish

6. Verify publication:

   • Check npm registry: https://www.npmjs.com/package/eco-blockchain-sdk-ts
   • Install from npm: npm install eco-blockchain-sdk-ts

Private Registry

To publish to a private registry (e.g., GitHub Packages):

1. Configure .npmrc:

   @eco:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${NPM_TOKEN}

2. Update package name to include scope: @eco/blockchain-sdk-ts

3. Publish:

   npm publish

License

MIT