npm package: @realiotech/client-signer
Description: Realio SDK for client side cross chain message signing
Author: Realio
Latest version: 1.4.0

# Client Signer SDK

A client side cross-chain message signing SDK for Realio, supporting multiple blockchain protocols.

## Installation

```bash
npm install @realiotech/client-signer
```

## Development

### Branching Strategy

This project uses a simple branching strategy:

- `main` is the only permanent branch
- All development happens through pull requests to `main`
- No staging branch is used
- Feature branches should be created from `main`

### Development Workflow

1. Create a feature branch from `main`:

   ```bash
   git checkout main
   git pull origin main
   git checkout -b feature/your-feature-name
   ```

2. Make your changes and commit them:

   ```bash
   git add .
   git commit -m "feat: your feature description"
   ```

3. Push your branch and create a PR:

   ```bash
   git push origin feature/your-feature-name
   ```

   Then create a pull request to merge into `main`.

4. After review and approval, your PR will be merged to `main`

### Development Commands

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Build for development (with sourcemaps)
npm run build:dev

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## Usage

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.BITCOIN,
  mnemonic: 'your mnemonic here',
  options: { mainnet: true },
});

const result = await signer.signTransaction(unsignedTx);
```

## Supported Protocols

- Bitcoin
- EVM
- Tendermint
- Stellar
- Algorand
- Solana

## API Integration

This SDK is tightly coupled with Realio's core transaction API. It supports signing transactions from the following APIs:

### Supported APIs

- [Send-Token Unsigned](https://api.realiostage.app/docs#/wallets/createSendTokenTransaction)
- Staking Transactions (Tendermint only):
  - Delegate (stake tokens)
  - Undelegate (unstake tokens)
  - Redelegate (move stake between validators)
  - Withdraw Delegator Rewards (claim rewards from single validator)
  - Withdraw All Rewards (claim rewards from multiple validators)

### Input Data Format

The SDK expects transaction data to be in the format provided by Realio's core transaction API. This means:

1. The input transaction data must be obtained by calling the core API's transaction creation methods
2. The signer will not validate or modify the transaction structure - it only handles the signing process
3. For Tendermint staking transactions, the `messageType` field determines which transaction type to create

## API Reference

### createSigner

```typescript
function createSigner<T extends ProtocolOptions>(options: CreateSignerOptions<T>): Signer;
```

#### Parameters

- `options`: Configuration object containing:
  - `protocol`: The blockchain protocol to use (from `PROTOCOL_NAMES`)
  - `mnemonic`: BIP39 mnemonic phrase
  - `options`: Protocol-specific options (optional)

#### Returns

A `Signer` instance with a `signTransaction` method.

### Signer Interface

```typescript
interface Signer {
  signTransaction(tx: string): Promise<SignedTx>;
}
```

### Protocol Options

#### BitcoinOptions

```typescript
interface BitcoinOptions {
  mainnet: boolean; // true for mainnet, false for testnet
}
```

#### StellarOptions

```typescript
interface StellarOptions {
  mainnet: boolean; // true for mainnet, false for testnet
}
```

#### TendermintOptions

```typescript
interface TendermintOptions {
  chain: Chain;
  sender: Sender;
}
```

## Examples

### Bitcoin Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.BITCOIN,
  mnemonic: 'your mnemonic here',
  options: { mainnet: false }, // Required: true for mainnet, false for testnet
});

const result = await signer.signTransaction(unsignedPsbtHex);
```

### EVM Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.EVM,
  mnemonic: 'your mnemonic here',
});

const result = await signer.signTransaction(unsignedTxHex);
```

### Tendermint Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.TENDERMINT,
  mnemonic: 'your mnemonic here',
  options: {
    chain: {
      chainId: 3300,
      cosmosChainId: 'realionetwork_3300-4',
    },
    sender: {
      accountAddress: 'realio...',
      pubkey: 'AzUx...',
      accountNumber: 124,
      sequence: 1,
    },
  },
});

const result = await signer.signTransaction(unsignedTx);
```

### Tendermint Staking Transactions

The Tendermint signer supports staking operations. The transaction data must include a `messageType` field to specify the operation type.

#### Supported Message Types

| messageType                 | Description                            |
| --------------------------- | -------------------------------------- |
| `send`                      | Token transfer (default)               |
| `delegate`                  | Stake tokens to a validator            |
| `undelegate`                | Unstake tokens from a validator        |
| `redelegate`                | Move stake between validators          |
| `delegate-evm`              | Stake ERC-20 tokens to a validator     |
| `undelegate-evm`            | Unstake ERC-20 tokens from a validator |
| `redelegate-evm`            | Move ERC-20 stake between validators   |
| `withdraw-delegator-reward` | Claim rewards from single validator    |
| `withdraw-all-rewards`      | Claim rewards from multiple validators |

#### Staking Transaction Example

```typescript
import { createSigner, PROTOCOL_NAMES, CosmosMessageType } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.TENDERMINT,
  mnemonic: 'your mnemonic here',
  options: {
    chain: {
      chainId: 3300,
      cosmosChainId: 'realionetwork_3300-4',
    },
    sender: {
      accountAddress: 'realio...',
      pubkey: 'AzUx...',
      accountNumber: 124,
      sequence: 1,
    },
  },
});

// The unsignedTx is hex-encoded JSON from the API containing messageType
// Example delegate transaction structure:
// {
//   messages: [{ validatorAddress: '...', amount: '...', denom: 'ario' }],
//   memo: '',
//   feeData: { amount: '...', denom: 'ario', gas: '...' },
//   messageType: 'delegate'
// }
const result = await signer.signTransaction(unsignedStakingTx);
```

### Stellar Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.STELLAR,
  mnemonic: 'your mnemonic here',
  options: { mainnet: false }, // Required: true for mainnet, false for testnet
});

const result = await signer.signTransaction(unsignedXdr);
```

### Algorand Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.ALGORAND,
  mnemonic: 'your mnemonic here',
});

const result = await signer.signTransaction(unsignedTxBase64);
```

### Solana Transaction Signing

```typescript
import { createSigner, PROTOCOL_NAMES } from 'client-signer';

const signer = createSigner({
  protocol: PROTOCOL_NAMES.SOLANA,
  mnemonic: 'your mnemonic here',
});

const result = await signer.signTransaction(unsignedTxBase64);
```

## Deployment

### Versioning

This package follows [Semantic Versioning](https://semver.org/). The version in `package.json` should be a semantic version number without the 'v' prefix (e.g., `"1.0.0"`).

### Release Process

All changes, including releases, should be made through pull requests to the main branch. Never commit directly to main.

1. Create a new branch for the release:

   ```bash
   git checkout -b release/1.0.0
   ```

2. Update the version in `package.json`:

   ```json
   {
     "version": "1.0.0" // Update this number
   }
   ```

3. Commit the version change:

   ```bash
   git add package.json
   git commit -m "chore: bump version to 1.0.0"
   ```

4. Push the branch and create a PR:

   ```bash
   git push origin release/1.0.0
   ```

   Then create a pull request to merge into main.

5. After the PR is approved and merged to main, create and push a tag (with 'v' prefix):
   ```bash
   git checkout main
   git pull origin main
   git tag v1.0.0
   git push origin v1.0.0
   ```

The CI/CD pipeline will automatically:

- Run tests on the PR
- Run tests on merge to main
- When a tag is pushed:
  - Verify the version matches package.json
  - Build the package
  - Publish to npm

### Version Format

- Package version (package.json): `1.0.0` (no 'v' prefix)
- Git tag: `v1.0.0` (with 'v' prefix)
- CI will ensure they match (ignoring the 'v' prefix)

## Tools

- tsup: TypeScript bundler
- Vitest: Testing framework
- ESLint: Code linting
- Prettier: Code formatting