🔐 ecadd

The simplest Bitcoin scalar addition library

Add scalar values to EC points on secp256k1 with zero complexity. Perfect for Bitcoin developers who need clean, fast elliptic curve operations.

✨ Features

• 🚀 Blazing fast - Built on tiny-secp256k1
• 🔐 Bitcoin native - Handles compressed pubkeys and Taproot x-coordinates
• 📦 Zero dependencies - Well, one tiny one
• 🎯 Simple API - One function to rule them all
• 🌈 Beautiful CLI - With colors and emojis
• 🔧 Pure JavaScript - No TypeScript complexity
• 🔤 Smart padding - Automatically pads short hex values with leading zeros

🚀 Quick Start

npm install ecadd

const { ecadd } = require('ecadd')

// Add scalar value to a compressed pubkey
const result = ecadd(
  '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
  1
)

console.log(result) // 03c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5

🔧 CLI Usage

# Install globally
npm install -g ecadd

# Add scalar to compressed pubkey
ecadd 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798 1

# Add scalar to Taproot x-coordinate (returns multiple possibilities)
ecadd 79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798 42

# Short hex values are automatically padded
ecadd 1234 ff

# Get help
ecadd --help

📖 API Reference

ecadd(point, scalar)

Adds a scalar value to an EC point on secp256k1.

Parameters:

• point (string): EC point in hex
• scalar (string|number): Scalar value to add

Point formats:

• Compressed pubkey: ≤66 hex chars starting with 02 or 03 (auto-padded)
• Taproot x-coordinate: ≤64 hex chars (auto-padded, tries both 02 and 03 prefixes)

Scalar formats:

• Number: 1, 42, 255
• Hex string: "ff", "1a2b", "0x1234"

Returns:

• string: Single result for compressed pubkey
• string[]: Multiple results for Taproot x-coordinate (both 02 and 03 prefixes)

isValidPoint(pointHex)

Validates if a hex string is a valid EC point.

Parameters:

• pointHex (string): Point in hex format

Returns:

• boolean: true if valid, false otherwise

🎯 Examples

Basic Scalar Addition

const { ecadd } = require('ecadd')

// Add scalar value to generator point
const G = '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
const result = ecadd(G, 1)
console.log(result) // 03c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5

Taproot X-Coordinates

const { ecadd } = require('ecadd')

// Add scalar to Taproot x-coordinate (32 bytes)
const x1 = '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'

const results = ecadd(x1, 42)
console.log(results) // Array of possible results (both 02 and 03 prefixes)

Validation

const { isValidPoint } = require('ecadd')

console.log(
  isValidPoint(
    '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
  )
) // true
console.log(isValidPoint('invalid')) // false

Automatic Padding

const { ecadd } = require('ecadd')

// Short hex points are automatically padded with leading zeros
const result1 = ecadd('1234', 42)
console.log(result1) // Treats as taproot x-coordinate, returns array

// Short compressed pubkeys are padded too
const result2 = ecadd('021234', 'ff')
console.log(result2) // Single result for compressed pubkey

🎨 CLI Examples

# Beautiful, colorful output
$ ecadd 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798 1

🔐 Adding scalar to EC point...
Point: 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798
Scalar: 1

✅ Result: 03c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5

🔬 How It Works

1. Parse Point: Handles compressed pubkeys (≤66 hex chars starting with 02/03) and Taproot x-coordinates (≤64 hex chars)
2. Parse Scalar: Converts numbers or hex strings to 32-byte scalars
3. Scalar Multiplication: Computes scalar × G (where G is the generator point)
4. Point Addition: Adds the original point to the scalar point
5. Smart Padding: Short hex values are padded with leading zeros automatically
6. Dual Results: Taproot x-coordinates return both 02 and 03 prefix possibilities

🤝 Contributing

We love contributions! Here's how to get started:

1. Fork the repo
2. Create a feature branch: git checkout -b my-new-feature
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

📝 License

MIT © ecadd contributors

🌟 Why ecadd?

• 🎯 Focused: Does one thing perfectly
• 🚀 Fast: Minimal overhead, maximum performance
• 🔐 Secure: Built on battle-tested tiny-secp256k1
• 📦 Tiny: No bloat, just pure functionality
• 🎨 Beautiful: CLI that sparks joy