npm package: @p2p-org/signer-sdk
Description: A unified blockchain transaction signing SDK that provides secure, local signing for 15+ blockchain networks. Sign transactions offline without exposing private keys to external services.
Author: Tarasevich Timofei
Latest version: 0.0.2

# @p2p-org/signer-sdk

A unified blockchain transaction signing SDK that provides secure, local signing for 15+ blockchain networks. Sign transactions offline without exposing private keys to external services.

## Features

- 🔐 **Secure Local Signing** - Private keys never leave your environment
- 🌐 **Multi-Blockchain Support** - 15+ integrated blockchain networks
- 🛠️ **Unified Interface** - Consistent API across all supported chains
- 📦 **TypeScript First** - Full type safety and IntelliSense support
- 🖥️ **CLI & SDK** - Use as a library or command-line tool

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Supported Blockchains](#supported-blockchains)
- [Usage Examples](#usage-examples)
- [CLI Usage](#cli-usage)
- [API Reference](#api-reference)
- [Development](#development)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)

## Installation

### As a Library

```bash
# Using npm
npm install @p2p-org/signer-sdk

# Using yarn
yarn add @p2p-org/signer-sdk

# Using pnpm
pnpm add @p2p-org/signer-sdk
```

### As a CLI Tool

```bash
# Install globally
npm install -g @p2p-org/signer-sdk

# Or use directly with npx
npx @p2p-org/signer-sdk --help
```

## Quick Start

### Basic Example

```typescript
import { SignerFactory, Signers } from '@p2p-org/signer-sdk';

// Create configuration for your blockchain
const config = {
  networkName: 'mainnet',
  btcPrivateKey: 'YOUR_PRIVATE_KEY',
};

// Create a signer instance
const signer = SignerFactory.createSigner(Signers.Btc, config);

// Sign a transaction
const unsignedTransaction = '70736274ff01007d...';
const signedTx = await signer.sign({ unsignedTransaction });

console.log('Signed transaction:', signedTx);
```

## Supported Blockchains

| Blockchain | Status | Networks | Configuration | Transaction Format |
|------------|--------|----------|---------------|-------------------|
| **Aptos** | ✅ Available | mainnet, testnet | [Config](src/aptos/interfaces/aptos-config.ts) | [Transaction](src/aptos/interfaces/aptos-transaction.ts) |
| **Avail** | ✅ Available | mainnet, testnet | [Config](src/avail/interfaces/avail-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Babylon** | ✅ Available | babylon-mainnet, babylon-testnet | [Config](src/babylon/interfaces/babylon-config.ts) | [Transaction](src/babylon/interfaces/babylon-transaction.ts) |
| **Bitcoin** | ✅ Available | mainnet, testnet | [Config](src/btc/interfaces/btc-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Celestia** | ✅ Available | mainnet, testnet | [Config](src/celestia/interfaces/celestia-config.ts) | [Transaction](src/celestia/interfaces/celestia-transaction.ts) |
| **Cosmos** | ✅ Available | cosmoshub-4, theta-testnet-001 | [Config](src/cosmos/interfaces/cosmos-config.ts) | [Transaction](src/cosmos/interfaces/cosmos-transaction.ts) |
| **dYdX** | ✅ Available | mainnet, testnet | [Config](src/dydx/interfaces/dydx-config.ts) | [Transaction](src/dydx/interfaces/dydx-transaction.ts) |
| **Ethereum** | ✅ Available | mainnet, sepolia, holesky | [Config](src/ethereum/interfaces/ethereum-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Polkadot** | ✅ Available | westend, kusama, polkadot | [Config](src/polkadot/interfaces/polkadot-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Sei** | ✅ Available | pacific-1, atlantic-2 | [Config](src/sei/interfaces/sei-config.ts) | [Transaction](src/sei/interfaces/sei-transaction.ts) |
| **Solana** | ✅ Available | mainnet-beta, testnet, devnet | [Config](src/solana/interfaces/solana-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Story** | ✅ Available | mainnet, aeneid | [Config](src/story/interfaces/story-config.ts) | [Transaction](src/story/interfaces/story-transaction.ts) |
| **Sui** | ✅ Available | mainnet, testnet | [Config](src/sui/interfaces/sui-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **The Graph** | ✅ Available | mainnet | [Config](src/the-graph/interfaces/thegraph-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Tezos** | ✅ Available | mainnet | [Config](src/tezos/interfaces/tezos-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **TON** | ✅ Available | mainnet, testnet | [Config](src/ton/interfaces/ton-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Tron** | ✅ Available | mainnet, nile | [Config](src/tron/interfaces/tron-config.ts) | [Transaction](src/common/interfaces/common-unsigned-transaction.ts) |
| **Cardano** | 🚧 Coming Soon | - | - | - |
| **Near** | 🚧 Coming Soon | - | - | - |

## Usage Examples

### Solana - Simple Transaction Signing

```typescript
import { SignerFactory, Signers } from '@p2p-org/signer-sdk';

const config = {
  networkName: 'mainnet-beta',
  solanaAddress: 'YOUR_SOLANA_ADDRESS',
  solanaPrivateKeys: ['YOUR_PRIVATE_KEY'], // Array of private keys
};

const signer = SignerFactory.createSigner(Signers.Solana, config);

const unsignedTransaction = 'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAg...';
const signedTx = await signer.sign({ unsignedTransaction });

console.log('Signed transaction:', signedTx);
```

### Cosmos - Staking Transaction

```typescript
import { SignerFactory, Signers } from '@p2p-org/signer-sdk';
import axios from 'axios';

const config = {
  cosmosNodeRpc: 'https://cosmos-rpc.example.com',
  networkName: 'cosmoshub-4',
  cosmosAddress: 'cosmos1...',
  cosmosMnemonic: 'your twelve word mnemonic phrase here ...',
};

// Create a staking transaction (example with P2P Staking API)
const stakingData = await axios.post(
  'https://api.p2p.org/api/v1/cosmos/cosmoshub-4/staking/stake',
  {
    stashAccountAddress: config.cosmosAddress,
    amount: 1.5,
  },
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

// Sign the transaction
const signer = SignerFactory.createSigner(Signers.Cosmos, config);
const signedTx = await signer.sign(stakingData.data.result.transactionData);

console.log('Signed staking transaction:', signedTx);
```

### Polkadot - Multiple Operations

```typescript
import { SignerFactory, Signers } from '@p2p-org/signer-sdk';

const config = {
  polkadotNodeRpc: 'wss://westend-rpc.polkadot.io',
  networkName: 'westend',
  polkadotAddress: '5...',
  polkadotFileContent: 'ENCRYPTED_KEYSTORE_JSON',
  polkadotFilePassword: 'YOUR_PASSWORD',
};

const signer = SignerFactory.createSigner(Signers.Polkadot, config);

// Sign multiple transactions
const bondTx = await signer.sign({ unsignedTransaction: 'BOND_TX_DATA' });
const nominateTx = await signer.sign({ unsignedTransaction: 'NOMINATE_TX_DATA' });

// Important: Close the signer when done (required for Polkadot)
signer.close();
```

### Ethereum - EIP-1559 Transaction

```typescript
import { SignerFactory, Signers } from '@p2p-org/signer-sdk';

const config = {
  networkName: 'mainnet',
  ethereumPrivateKey: 'YOUR_PRIVATE_KEY',
};

const signer = SignerFactory.createSigner(Signers.Ethereum, config);

const unsignedTransaction = '0x02f86f0180808504a817c80082520894...';
const signedTx = await signer.sign({ unsignedTransaction });

console.log('Signed EIP-1559 transaction:', signedTx);
```

## CLI Usage

The SDK includes a powerful CLI for signing transactions directly from the command line.

### Basic CLI Commands

```bash
# Show help
p2p-signer --help

# Sign a Solana transaction
p2p-signer solana sign \
  --network-name="mainnet-beta" \
  --address="YOUR_ADDRESS" \
  --private-keys='["YOUR_PRIVATE_KEY"]' \
  --unsigned-transaction="BASE64_TX_DATA"

# Sign a Cosmos transaction with mnemonic
p2p-signer cosmos sign \
  --network-name="cosmoshub-4" \
  --node-rpc="https://cosmos-rpc.example.com" \
  --address="cosmos1..." \
  --mnemonic="your twelve word mnemonic phrase" \
  --unsigned-transaction='{"unsignedTransaction":"..."}'

# Sign a Bitcoin PSBT
p2p-signer btc sign \
  --network-name="mainnet" \
  --private-key="YOUR_PRIVATE_KEY" \
  --unsigned-transaction="PSBT_BASE64"
```

For detailed CLI documentation, see [CLI README](src/cli/README.md).

## API Reference

### SignerFactory

The main entry point for creating blockchain signers.

```typescript
class SignerFactory {
  static createSigner<T extends Signers>(
    blockchain: T,
    config: SignerConfig<T>
  ): Signer;
}
```

### Signer Interface

All blockchain signers implement this common interface:

```typescript
interface Signer<UnsignedTx, SignedTx, Info> {
  sign(transaction: UnsignedTx): Promise<SignedTx>;
  info(): Promise<Info>;
  close(): Promise<void>;
}
```

### Configuration Types

Each blockchain has specific configuration requirements:

```typescript
// Example: Solana Configuration
interface SolanaConfig {
  networkName: string;
  solanaAddress: string;
  solanaPrivateKeys: string[];
}

// Example: Cosmos Configuration
interface CosmosConfig {
  networkName: string;
  cosmosNodeRpc: string;
  cosmosAddress: string;
  cosmosMnemonic: string;
}
```

## Development

### Prerequisites

- Node.js >= 16
- TypeScript >= 4.5

### Setup

```bash
# Clone the repository
git clone https://github.com/p2p-org/signer-sdk.git
cd signer-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint
```

### Adding a New Blockchain

1. Create a new directory under `src/` for your blockchain
2. Implement the `Signer` interface
3. Add configuration and transaction interfaces
4. Register in `SignerFactory` and `Signers` enum
5. Add CLI command (optional)
6. Write tests and documentation

Example structure:
```
src/
└── mychain/
    ├── index.ts
    ├── mychain-signer.ts
    ├── constants/
    │   └── mychain-networks.ts
    └── interfaces/
        ├── mychain-config.ts
        └── mychain-transaction.ts
```

## Security

### Best Practices

- **Never share or commit private keys**
- **Use environment variables for sensitive data**
- **Run signing operations in secure environments**
- **Validate all inputs before signing**
- **Keep the SDK updated for security patches**

### Security Features

- ✅ Input validation on all configurations
- ✅ TypeScript type safety
- ✅ No private key storage or transmission

### Reporting Security Issues

Please report security vulnerabilities to security@p2p.org. Do not create public issues for security problems.

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Code Style

- Follow TypeScript best practices
- Use ESLint and Prettier configurations
- Write comprehensive tests
- Document new features

## Support

- 🐛 Issues: [GitHub Issues](https://github.com/p2p-org/signer-sdk/issues)


## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

Built with ❤️ by [P2P.org](https://p2p.org)