plugin-coti/README.md

COTI blockchain plugin for ElizaOS - enables private token operations and encrypted transactions

# COTI Plugin

COTI blockchain plugin for ElizaOS - enables private token operations and encrypted transactions on the COTI network.

## Features

### Native COTI Operations
- **Native COTI Balance Checking**: Get COTI token balances for any address
- **COTI Token Transfers**: Send COTI tokens to other addresses
- **Account Management**: List and manage COTI accounts
- **Wallet Information**: Get detailed wallet and network information

### Private ERC20 Token Operations
- **Deploy Private ERC20 Contracts**: Create new private token contracts
- **Check Private ERC20 Balances**: Get balances for private tokens
- **Transfer Private ERC20 Tokens**: Send private tokens between addresses

### Private ERC721 NFT Operations
- **Deploy Private ERC721 Contracts**: Create new private NFT collections
- **Mint Private NFTs**: Create new NFTs with encrypted metadata
- **Transfer Private NFTs**: Send NFTs between addresses
- **Get Private NFT Metadata**: Retrieve and decrypt NFT token URIs

### Privacy Features
- **Encrypted Transactions**: All operations use COTI's privacy-enhanced blockchain
- **Private Metadata**: NFT metadata is encrypted and only accessible to authorized parties
- **Confidential Balances**: Token balances are kept private using COTI's privacy technology

## Installation

```bash
npm install plugin-coti
```

## Configuration

Set the following environment variables:

- `COTI_PRIVATE_KEY`: Private key for your COTI wallet (required)
- `COTI_AES_KEY`: AES key for COTI private token encryption (required for private NFT operations)
- `COTI_RPC_URL`: RPC URL for COTI network (optional, defaults to testnet)
- `COTI_NETWORK_ID`: Network ID for COTI blockchain (optional, defaults to 7701)

### Important: AES Key for Private Operations

For private token operations (especially NFT minting), you **must** provide a `COTI_AES_KEY`. This key is used to encrypt token metadata before storing it on the blockchain, ensuring privacy. Without this key, private NFT minting will fail.

Example `.env` file:
```
COTI_PRIVATE_KEY=your_private_key_here
COTI_AES_KEY=your_aes_key_here
COTI_RPC_URL=https://testnet.coti.io/rpc
COTI_NETWORK_ID=7701
```

## Usage

```typescript
import { plugin } from 'plugin-coti';

// Use the plugin in your ElizaOS agent
```

## Available Actions

### Native COTI Operations

#### GET_NATIVE_BALANCE
Check COTI token balance for an address.

**Triggers**: "What's my COTI balance?", "Check balance for 0x...", "Show my COTI balance"

#### TRANSFER_NATIVE
Transfer COTI tokens to another address.

**Triggers**: "Send 10 COTI to 0x...", "Transfer 5.5 COTI to alice", "Send COTI to bob"

#### LIST_ACCOUNTS
List all configured COTI accounts.

**Triggers**: "Show me my COTI accounts", "What accounts do I have?", "List my accounts"

#### WALLET_INFO
Get detailed wallet and network information.

**Triggers**: "Show me my wallet information", "What's my wallet status?", "Wallet info"

### Private ERC20 Token Operations

#### DEPLOY_PRIVATE_ERC20_CONTRACT
Deploy a new private ERC20 token contract on the COTI blockchain.

**Triggers**: "Deploy a new ERC20 token", "Create a private token", "Deploy token called 'MyToken' with symbol 'MTK'"

#### GET_PRIVATE_ERC20_BALANCE
Check balance for a private ERC20 token.

**Triggers**: "Check my token balance for contract 0x...", "What's my balance for token 0x...", "Show token balance"

#### TRANSFER_PRIVATE_ERC20_TOKEN
Transfer private ERC20 tokens between addresses.

**Triggers**: "Transfer 100 tokens from contract 0x... to 0x...", "Send tokens to alice", "Transfer my tokens"

### Private ERC721 NFT Operations

#### DEPLOY_PRIVATE_ERC721_CONTRACT
Deploy a new private ERC721 NFT contract on the COTI blockchain.

**Triggers**: "Deploy a new NFT collection", "Create NFT collection called 'My Art' with symbol 'ART'", "Deploy private NFT"

#### MINT_PRIVATE_ERC721_TOKEN
Mint a new private NFT with encrypted metadata.

**Triggers**: "Mint an NFT to alice with metadata https://...", "Create NFT for bob", "Mint private NFT"

#### TRANSFER_PRIVATE_ERC721_TOKEN
Transfer private NFTs between addresses.

**Triggers**: "Transfer NFT token ID 123 to bob", "Send NFT to alice", "Transfer my NFT"

#### GET_PRIVATE_ERC721_TOKEN_URI
Get the metadata URI for a private NFT (decrypted).

**Triggers**: "Get metadata for NFT token 456", "Show NFT URI for token 123", "What's the metadata for my NFT"

## Structure

```
plugin-coti/
├── src/
│   ├── actions/                           # COTI blockchain actions
│   │   ├── getNativeBalance.ts           # Get COTI balance
│   │   ├── transferNative.ts             # Transfer COTI tokens
│   │   ├── listAccounts.ts               # List accounts
│   │   ├── walletInfo.ts                 # Wallet information
│   │   ├── deployPrivateErc20Contract.ts # Deploy ERC20 contracts
│   │   ├── getPrivateErc20Balance.ts     # Get ERC20 balances
│   │   ├── transferPrivateErc20Token.ts  # Transfer ERC20 tokens
│   │   ├── deployPrivateErc721Contract.ts # Deploy NFT contracts
│   │   ├── mintPrivateErc721Token.ts     # Mint NFTs
│   │   ├── transferPrivateErc721Token.ts # Transfer NFTs
│   │   └── getPrivateErc721TokenUri.ts   # Get NFT metadata
│   ├── providers/                        # Blockchain providers
│   │   ├── cotiProvider.ts               # COTI network provider
│   │   └── wallet.ts                     # Wallet management
│   ├── types/                            # Type definitions
│   │   └── index.ts                      # Shared types
│   └── index.ts                          # Plugin export
├── package.json                          # Dependencies and config
└── README.md                             # This file
```

## Example Usage

### Deploy and Use Private ERC20 Token
```typescript
// Deploy a new private ERC20 token
"Deploy a new ERC20 token called 'MyToken' with symbol 'MTK' and 18 decimals"

// Check token balance
"Check my token balance for contract 0x1234567890123456789012345678901234567890"

// Transfer tokens
"Transfer 100 tokens from contract 0x1234... to 0x5678..."
```

### Deploy and Use Private NFT Collection
```typescript
// Deploy a new NFT collection
"Deploy a new NFT collection called 'My Art Gallery' with symbol 'ART'"

// Mint an NFT
"Mint an NFT to alice with metadata https://example.com/art/1.json"

// Transfer NFT
"Transfer NFT token ID 123 to bob"

// Get NFT metadata
"Get the metadata URI for NFT token 456"
```

### Native COTI Operations
```typescript
// Check COTI balance
"What's my COTI balance?"

// Transfer COTI
"Send 10 COTI to 0x1234567890123456789012345678901234567890"

// List accounts
"Show me my COTI accounts"

// Get wallet info
"Show me my wallet information"
```

## Development Commands

```bash
# Start in development mode with hot reload
npm run dev

# Start in production mode
npm run start

# Build the plugin
npm run build

# Run tests
npm test

# Format code
npm run format
```

## Security

- **Never share your private key** - Keep your COTI_PRIVATE_KEY secure
- **Use testnet for development** - Test all operations on testnet first
- **Verify transaction details** - Always double-check addresses and amounts
- **Private data protection** - Remember that while transactions are private, contract addresses are still visible on-chain
- **Metadata encryption** - NFT metadata is encrypted but ensure your metadata URLs are also secure

## Troubleshooting

### Common Issues

1. **"Insufficient funds" error**: Make sure your wallet has enough COTI tokens for gas fees
2. **"Contract not found" error**: Verify the contract address is correct and deployed on the right network
3. **"Private key invalid" error**: Check that your COTI_PRIVATE_KEY is properly formatted
4. **"Network connection failed" error**: Verify your COTI_RPC_URL is accessible

### Debug Mode

Enable debug logging by setting:
```bash
DEBUG=plugin-coti:*
```

## License

UNLICENSED