@paulstinchcombe/kami721c-sdk/README.md

SDK for interacting with KAMI721C NFT contracts

# KAMI721C SDK

A TypeScript SDK for interacting with KAMI721C NFT contracts on Ethereum and EVM-compatible chains.

## Installation

```bash
npm install kami721c-sdk
```

## Features

-   Deploy and interact with KAMI721C NFT contracts
-   Mint NFTs with USDC payment
-   Handle royalties for both minting and transfers
-   Platform commission support
-   Role-based access control
-   Token sales with automatic royalty distribution
-   Transaction queue management for sequential operations
-   Enhanced error handling and logging

## Usage

This SDK provides a wrapper for interacting with KAMI721C NFT contracts.

### Deploying a New Contract

```typescript
import { ethers } from 'ethers';
import { KAMI721CFactory } from 'kami721c-sdk';

// Connect to an Ethereum provider with a signer
const provider = new ethers.JsonRpcProvider('https://ethereum-goerli.publicnode.com');
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Create a factory instance
const factory = new KAMI721CFactory(wallet);

// Deploy a new KAMI721C contract
const usdcAddress = '0x...'; // USDC token address
const name = 'My NFT Collection';
const symbol = 'MYNFT';
const baseURI = 'ipfs://bafkreid4xrk5mxq4t3ilfhwmvpn5scy2kmsra7gm7a3kscnudsyb4dtsqq/';
const initialMintPrice = 1000000n; // 1 USDC (6 decimals)
const platformAddress = wallet.address; // Address to receive platform commission
const platformCommission = 500; // 5% commission in basis points

const nftContract = await factory.deploy(usdcAddress, name, symbol, baseURI, initialMintPrice, platformAddress, platformCommission);
const contractAddress = nftContract.getAddress();
console.log(`Contract deployed at: ${contractAddress}`);
```

### Connecting to an Existing Contract

```typescript
import { ethers } from 'ethers';
import { KAMI721C } from 'kami721c-sdk';

// Connect to an Ethereum provider
const provider = new ethers.JsonRpcProvider('https://ethereum-goerli.publicnode.com');

// If you need to use a signer for write operations
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Connect to an existing KAMI721C contract
const contractAddress = '0x...'; // Your contract address
const nftContract = new KAMI721C(wallet, contractAddress);

// Or connect using just a provider for read-only operations
const readOnlyContract = new KAMI721C(provider, contractAddress);
```

### Reading Contract Information

```typescript
// Get basic contract information
const name = await nftContract.name();
const symbol = await nftContract.symbol();
const totalSupply = await nftContract.totalSupply();
const mintPrice = await nftContract.mintPrice();
const platformCommission = await nftContract.getPlatformCommission();
const royaltyPercentage = await nftContract.royaltyPercentage();

// Get token information
const tokenId = 0; // Token IDs are 0-based
const owner = await nftContract.ownerOf(tokenId);
const tokenURI = await nftContract.tokenURI(tokenId);
const balance = await nftContract.balanceOf(owner);
```

### Minting Tokens

```typescript
// Get current mint price
const mintPrice = await nftContract.mintPrice();
console.log(`Mint price: ${ethers.formatUnits(mintPrice, 6)} USDC`);

// Approve USDC for the contract (required before minting)
const usdcAbi = ['function approve(address spender, uint256 amount) returns (bool)'];
const usdcContract = new ethers.Contract(usdcAddress, usdcAbi, wallet);
await usdcContract.approve(nftContract.getAddress(), mintPrice);

// Mint a new token
const mintTx = await nftContract.mint();
const receipt = await mintTx.wait();
console.log(`Token minted in block ${receipt?.blockNumber}`);
```

### Managing Mint Price

```typescript
// Get current mint price
const currentPrice = await nftContract.mintPrice();
console.log(`Current mint price: ${ethers.formatUnits(currentPrice, 6)} USDC`);

// Set a new mint price (requires OWNER_ROLE)
const newPrice = 2000000n; // 2 USDC (6 decimals)
await nftContract.setMintPrice(newPrice);
```

### Managing Platform Commission

```typescript
// Get current platform commission details
const commission = await nftContract.getPlatformCommission();
console.log(`Platform commission: ${commission.percentage / 100}% to ${commission.address}`);

// Update platform commission (requires OWNER_ROLE)
const newCommission = 300; // 3% in basis points
const newPlatformAddress = '0x...';
await nftContract.setPlatformCommission(newCommission, newPlatformAddress);
```

### Setting Royalties

The KAMI721C contract supports royalties for both minting and transfers:

```typescript
import { KAMI721C, RoyaltyData } from 'kami721c-sdk';

// Set the overall royalty percentage for transfers (requires OWNER_ROLE)
const royaltyPercentage = 1000; // 10% in basis points
await nftContract.setRoyaltyPercentage(royaltyPercentage);

// Create royalty data where receivers split 100% of the royalties
// In the new contract, the feeNumerator values must total to 10000 (100%)
const royalties: RoyaltyData[] = [
	{
		receiver: '0x...', // Primary receiver (80%)
		feeNumerator: 8000,
	},
	{
		receiver: '0x...', // Secondary receiver (20%)
		feeNumerator: 2000,
	},
];

// Set global mint royalties (for all newly minted tokens)
await nftContract.setMintRoyalties(royalties);

// Set global transfer royalties (distribution of the royaltyPercentage)
await nftContract.setTransferRoyalties(royalties);

// Set token-specific royalties (optional)
const tokenId = 0;
await nftContract.setTokenMintRoyalties(tokenId, royalties);
await nftContract.setTokenTransferRoyalties(tokenId, royalties);

// Get royalty information for a token sale
const salePrice = ethers.parseEther('1.0'); // 1 ETH
const royaltyInfo = await nftContract.royaltyInfo(tokenId, salePrice);
console.log(`Royalty receiver: ${royaltyInfo.receiver}`);
console.log(`Royalty amount: ${ethers.formatEther(royaltyInfo.royaltyAmount)} ETH`);
```

### Token Sales

The SDK supports token sales with automatic royalty payments:

```typescript
// Sell a token with royalties
const tokenId = 0; // Token ID to sell
const buyer = '0x...'; // Buyer's address
const salePrice = 5000000n; // 5 USDC (6 decimals)

// The buyer must approve USDC for the contract before the sale
const usdcAbi = ['function approve(address spender, uint256 amount) returns (bool)'];
const buyerWallet = new ethers.Wallet('BUYER_PRIVATE_KEY', provider);
const buyerUsdcContract = new ethers.Contract(usdcAddress, usdcAbi, buyerWallet);
await buyerUsdcContract.approve(nftContract.getAddress(), salePrice);

// Execute the sale (must be called by the token owner)
await nftContract.sellToken(buyer, tokenId, salePrice);
```

## Examples

The SDK includes complete examples in the `src/examples` directory.

### Running the Basic Usage Example

1. Clone this repository
2. Install dependencies:
    ```bash
    npm install
    ```
3. Create a `.env` file in the root directory using the `.env.example` template
4. Set your environment variables in the `.env` file:
    - `DEPLOY_NEW_CONTRACT`: Set to 'true' to deploy a new contract, 'false' to use existing
    - `CONTRACT_NAME`, `CONTRACT_SYMBOL`, `BASE_URI`: Used when deploying a new contract
    - `MINT_PRICE`: Initial mint price in USDC (with 6 decimals), defaults to 1000000 (1 USDC)
    - `PLATFORM_ADDRESS`: Address to receive platform commission (optional)
    - `PLATFORM_COMMISSION`: Platform commission in basis points (optional, default 500 or 5%)
    - `CONTRACT_ADDRESS`: Address of existing KAMI721C contract (when not deploying)
    - `PRIVATE_KEY`: Your Ethereum wallet private key
    - `RPC_URL`: URL for the Ethereum RPC node (defaults to SKALE testnet)
    - `MINT_TOKEN`: Set to 'true' to attempt minting a token
    - `UPDATE_MINT_PRICE`: Set to 'true' to update the mint price
    - `NEW_MINT_PRICE`: New mint price in USDC (with 6 decimals)
    - `ROYALTY_RECEIVER`: Address to receive royalties (optional)
    - `BUYER_ADDRESS`: Address for simulating a token sale (optional)
5. Run the example:
    ```bash
    npx ts-node src/examples/basic-usage.ts
    ```

## Important Notes

1. **Gas Fees**: When creating new wallets for testing, ensure they have enough native tokens (ETH/MATIC) for gas fees in addition to USDC for purchases.
2. **Transaction Queue**: The SDK includes a transaction queue system to manage sequential operations and prevent nonce conflicts.
3. **Error Handling**: The SDK provides detailed error messages and transaction information for better debugging.

## License

MIT

# kami-contract-sdk