@mayaprotocol/zcash-js/README.md

Zcash JavaScript library for Maya Protocol - Build and sign Zcash transparent transactions with memo support

# @mayaprotocol/zcash-js

A JavaScript/TypeScript library for interacting with Zcash nodes, designed for Maya Protocol integration.

## Installation

```bash
npm install @mayaprotocol/zcash-js
```

## Features

- Build and sign Zcash transparent transactions
- Support for memo fields in transactions
- UTXO management
- Fee calculation
- TypeScript support
- Works with Zcash mainnet and testnet

## Usage

### Basic Setup

```typescript
import { Config, buildTx, signAndFinalize, sendRawTransaction, getUTXOS } from '@mayaprotocol/zcash-js';

const config: Config = {
  server: {
    host: 'http://localhost:8232', // Your Zcash node URL
    user: 'your-rpc-user',
    password: 'your-rpc-password'
  },
  mainnet: true // or false for testnet
};
```

### Building and Sending a Transaction

```typescript
// Get UTXOs for the source address
const utxos = await getUTXOS('t1SourceAddress...', config);

// Build the transaction
const tx = await buildTx(
  0, // current block height
  't1SourceAddress...', // from address
  't1DestinationAddress...', // to address
  1000000, // amount in satoshis
  utxos,
  false // is this a memo transaction?
);

// Sign the transaction
const signedTx = await signAndFinalize(
  tx.height,
  'your-private-key-hex', // private key for source address
  tx.inputs,
  tx.outputs
);

// Send the transaction
const txid = await sendRawTransaction(signedTx, config);
console.log('Transaction ID:', txid);
```

### Sending a Transaction with Memo

```typescript
const tx = await buildTx(
  0,
  't1SourceAddress...',
  't1DestinationAddress...',
  1000000,
  utxos,
  false,
  'swap:cacao:maya1a7gg93dgwlulsrqf6qtage985ujhpu068zllw7' // memo text
);
```

### Address Generation

```typescript
import { pkToAddr, mainnetPrefix, testnetPrefix } from '@mayaprotocol/zcash-js';

// Generate address from public key
const publicKey = Buffer.from('02aa7ef4b1958837763303a675dea8f63eaf264494072f086acdbc78d0decb0d0f', 'hex');
const address = pkToAddr(publicKey, Buffer.from(testnetPrefix));
console.log('Address:', address); // tmUzzEDRjvE3QC8RBUFD7DTi5LLL4zAEvKW
```

### Address Validation

```typescript
import { isValidAddr, mainnetPrefix, testnetPrefix } from '@mayaprotocol/zcash-js';

// Validate testnet address
const isValid = isValidAddr('tmUzzEDRjvE3QC8RBUFD7DTi5LLL4zAEvKW', Buffer.from(testnetPrefix));
console.log('Is valid testnet address:', isValid); // true

// Validate mainnet address
const isMainnetValid = isValidAddr('t1R97mnhVqcE7Yq8p7yL4E29gy8etq9V9pG', Buffer.from(mainnetPrefix));
console.log('Is valid mainnet address:', isMainnetValid); // true
```

## API Reference

### Types

#### Config
```typescript
interface Config {
  server: {
    host: string;    // Zcash RPC endpoint URL
    user: string;    // RPC username
    password: string; // RPC password
  };
  mainnet: boolean; // true for mainnet, false for testnet
}
```

#### UTXO
```typescript
interface UTXO {
  txid: string;
  vout: number;
  amount: number;
  scriptPubKey: {
    hex: string;
    addresses: string[];
  };
  confirmations: number;
}
```

### Functions

- `getUTXOS(address: string, config: Config): Promise<UTXO[]>` - Get unspent transaction outputs for an address
- `buildTx(height: number, from: string, to: string, amount: number, utxos: UTXO[], extraFeeForMemo: boolean, memo?: string): Promise<BuildTxResult>` - Build a transaction
- `signAndFinalize(height: number, privateKey: string, inputs: Input[], outputs: Output[]): Promise<Buffer>` - Sign and finalize a transaction
- `sendRawTransaction(txb: Buffer, config: Config): Promise<string>` - Send a signed transaction
- `pkToAddr(publicKey: Buffer, prefix: Buffer): string` - Generate address from public key
- `isValidAddr(address: string, prefix: Buffer): boolean` - Validate an address
- `waitForTransaction(txid: string, config: Config, maxAttempts?: number): Promise<void>` - Wait for transaction confirmation

## Requirements

- Node.js >= 14
- A running Zcash node with RPC enabled

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and feature requests, please use the [GitLab issue tracker](https://gitlab.com/mayachain/chains/zcash/-/issues).