This commit is contained in:
Your Name 2025-08-14 15:38:15 -04:00
parent 5d13dd2df3
commit 22a0f47707
2 changed files with 0 additions and 517 deletions

484
README.md
View File

@ -1,484 +0,0 @@
# NOSTR Core Library
A comprehensive, production-ready C library for NOSTR protocol implementation with OpenSSL-based cryptography and extensive protocol support.
[![Version](https://img.shields.io/badge/version-0.1.20-blue.svg)](VERSION)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](#building)
## 🚀 Features
### Core Protocol Support
- **NIP-01**: Basic protocol flow - event creation, signing, and validation
- **NIP-04**: Encrypted direct messages (ECDH + AES-CBC + Base64)
- **NIP-05**: DNS-based internet identifier verification
- **NIP-06**: Key derivation from mnemonic (BIP39/BIP32 compliant)
- **NIP-11**: Relay information documents
- **NIP-13**: Proof of Work for events
- **NIP-44**: Versioned encrypted direct messages (ECDH + ChaCha20 + HMAC)
### Cryptographic Features
- **OpenSSL-Based**: Production-grade cryptography with OpenSSL backend
- **Secp256k1**: Complete elliptic curve implementation bundled
- **BIP39**: Mnemonic phrase generation and validation
- **BIP32**: Hierarchical deterministic key derivation
- **ChaCha20**: Stream cipher for NIP-44 encryption
- **AES-CBC**: Block cipher for NIP-04 encryption
- **Schnorr Signatures**: BIP-340 compliant signing and verification
### Networking & Relay Support
- **Multi-Relay Queries**: Synchronous querying with progress callbacks
- **Relay Pools**: Asynchronous connection management with statistics
- **OpenSSL WebSocket Communication**: Full relay protocol support with TLS
- **NIP-05 Identifier Verification**: DNS-based identity resolution
- **NIP-11 Relay Information**: Automatic relay capability discovery
- **Event Deduplication**: Automatic handling of duplicate events across relays
- **Connection Management**: Automatic reconnection and error handling
### Developer Experience
- **Minimal Dependencies**: Only requires OpenSSL, standard C library and math library
- **Thread-Safe**: Core cryptographic functions are stateless
- **Cross-Platform**: Builds on Linux, macOS, Windows
- **Comprehensive Examples**: Ready-to-run demonstration programs
- **Automatic Versioning**: Git-tag based version management
## 📦 Quick Start
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/yourusername/nostr_core_lib.git
cd nostr_core_lib
```
2. **Build the library:**
```bash
./build.sh lib
```
3. **Run examples:**
```bash
./build.sh examples
./examples/simple_keygen
```
### Usage Example
```c
#include "nostr_core/nostr_core.h"
#include <stdio.h>
int main() {
// Initialize library
if (nostr_init() != NOSTR_SUCCESS) {
fprintf(stderr, "Failed to initialize NOSTR library\n");
return 1;
}
// Generate keypair
unsigned char private_key[32], public_key[32];
nostr_generate_keypair(private_key, public_key);
// Convert to bech32 format
char nsec[100], npub[100];
nostr_key_to_bech32(private_key, "nsec", nsec);
nostr_key_to_bech32(public_key, "npub", npub);
printf("Private key: %s\n", nsec);
printf("Public key: %s\n", npub);
// Create and sign event
cJSON* event = nostr_create_and_sign_event(1, "Hello NOSTR!", NULL, private_key, 0);
if (event) {
char* json = cJSON_Print(event);
printf("Event: %s\n", json);
free(json);
cJSON_Delete(event);
}
nostr_cleanup();
return 0;
}
```
**Compile and run:**
```bash
gcc example.c -o example ./libnostr_core.a -lm
./example
```
## 🏗️ Building
### Build Targets
```bash
./build.sh lib # Build static library (default)
./build.sh examples # Build examples
./build.sh test # Run test suite
./build.sh clean # Clean build artifacts
./build.sh install # Install to system
```
### Manual Building
```bash
# Build static library
make
# Build examples
make examples
# Run tests
make test-crypto
# Clean
make clean
```
### Dependencies
**Required:**
- GCC or compatible C compiler
- Standard C library
- Math library (`-lm`)
**Included & Embedded (x64):**
- cJSON (JSON parsing)
- secp256k1 (elliptic curve cryptography)
- OpenSSL (complete cryptographic backend + TLS)
- curl (HTTP/HTTPS for NIP-05/NIP-11)
**ARM64 Additional Requirements:**
- System OpenSSL libraries (`-lssl -lcrypto`)
## 📚 API Documentation
### Initialization
```c
int nostr_init(void); // Initialize library (call first)
void nostr_cleanup(void); // Cleanup resources (call last)
const char* nostr_strerror(int error); // Get error message
```
### Key Management
```c
// Generate random keypair
int nostr_generate_keypair(unsigned char* private_key, unsigned char* public_key);
// Generate from mnemonic
int nostr_generate_mnemonic_and_keys(char* mnemonic, size_t mnemonic_size,
int account, unsigned char* private_key,
unsigned char* public_key);
// Derive from existing mnemonic
int nostr_derive_keys_from_mnemonic(const char* mnemonic, int account,
unsigned char* private_key, unsigned char* public_key);
// Format conversion
int nostr_key_to_bech32(const unsigned char* key, const char* hrp, char* output);
nostr_input_type_t nostr_detect_input_type(const char* input);
```
### Event Creation
```c
// Create and sign event
cJSON* nostr_create_and_sign_event(int kind, const char* content, cJSON* tags,
const unsigned char* private_key, time_t timestamp);
// Add proof of work
int nostr_add_proof_of_work(cJSON* event, const unsigned char* private_key,
int target_difficulty, void (*progress_callback)(...), void* user_data);
```
### Encryption (NIP-04 & NIP-44)
```c
// NIP-04 (AES-CBC)
int nostr_nip04_encrypt(const unsigned char* sender_private_key,
const unsigned char* recipient_public_key,
const char* plaintext, char* output, size_t output_size);
int nostr_nip04_decrypt(const unsigned char* recipient_private_key,
const unsigned char* sender_public_key,
const char* encrypted_data, char* output, size_t output_size);
// NIP-44 (ChaCha20)
int nostr_nip44_encrypt(const unsigned char* sender_private_key,
const unsigned char* recipient_public_key,
const char* plaintext, char* output, size_t output_size);
int nostr_nip44_decrypt(const unsigned char* recipient_private_key,
const unsigned char* sender_public_key,
const char* encrypted_data, char* output, size_t output_size);
```
### Relay Communication
```c
// Simple relay query
cJSON* nostr_query_relay_for_event(const char* relay_url, const char* pubkey_hex, int kind);
// Multi-relay synchronous queries
cJSON** synchronous_query_relays_with_progress(const char** relay_urls, int relay_count,
cJSON* filter, relay_query_mode_t mode,
int* result_count, int relay_timeout_seconds,
relay_progress_callback_t callback, void* user_data);
// Multi-relay publishing
publish_result_t* synchronous_publish_event_with_progress(const char** relay_urls, int relay_count,
cJSON* event, int* success_count,
int relay_timeout_seconds,
publish_progress_callback_t callback, void* user_data);
```
### Relay Pools (Asynchronous)
```c
// Create and manage relay pool
nostr_relay_pool_t* nostr_relay_pool_create(void);
int nostr_relay_pool_add_relay(nostr_relay_pool_t* pool, const char* relay_url);
void nostr_relay_pool_destroy(nostr_relay_pool_t* pool);
// Subscribe to events
nostr_pool_subscription_t* nostr_relay_pool_subscribe(
nostr_relay_pool_t* pool, const char** relay_urls, int relay_count, cJSON* filter,
void (*on_event)(cJSON* event, const char* relay_url, void* user_data),
void (*on_eose)(void* user_data), void* user_data);
// Run event loop
int nostr_relay_pool_run(nostr_relay_pool_t* pool, int timeout_ms);
int nostr_relay_pool_poll(nostr_relay_pool_t* pool, int timeout_ms);
```
### NIP-05 Identifier Verification
```c
// Lookup public key from NIP-05 identifier
int nostr_nip05_lookup(const char* nip05_identifier, char* pubkey_hex_out,
char*** relays, int* relay_count, int timeout_seconds);
// Verify NIP-05 identifier against public key
int nostr_nip05_verify(const char* nip05_identifier, const char* pubkey_hex,
char*** relays, int* relay_count, int timeout_seconds);
// Parse .well-known/nostr.json response
int nostr_nip05_parse_well_known(const char* json_response, const char* local_part,
char* pubkey_hex_out, char*** relays, int* relay_count);
```
### NIP-11 Relay Information
```c
// Fetch relay information document
int nostr_nip11_fetch_relay_info(const char* relay_url, nostr_relay_info_t** info_out, int timeout_seconds);
// Free relay information structure
void nostr_nip11_relay_info_free(nostr_relay_info_t* info);
```
## 📁 Examples
The library includes comprehensive examples:
- **`simple_keygen`** - Basic key generation and formatting
- **`keypair_generation`** - Advanced key management
- **`mnemonic_generation`** - BIP39 mnemonic handling
- **`mnemonic_derivation`** - NIP-06 key derivation
- **`utility_functions`** - General utility demonstrations
- **`input_detection`** - Input type detection and processing
- **`version_test`** - Library version information
Run all examples:
```bash
./build.sh examples
ls -la examples/
```
## 🧪 Testing
The library includes extensive tests:
```bash
# Run all tests
./build.sh test
# Individual test categories
cd tests && make test
```
**Test Categories:**
- **Core Functionality**: `simple_init_test`, `header_test`
- **Cryptography**: `chacha20_test`, `nostr_crypto_test`
- **NIP-04 Encryption**: `nip04_test`
- **NIP-05 Identifiers**: `nip05_test`
- **NIP-11 Relay Info**: `nip11_test`
- **NIP-44 Encryption**: `nip44_test`, `nip44_debug_test`
- **Key Derivation**: `nostr_test_bip32`
- **Relay Communication**: `relay_pool_test`, `sync_test`
- **HTTP/WebSocket**: `http_test`, `wss_test`
- **Proof of Work**: `test_pow_loop`
## 🏗️ Integration
### Static Library Integration
1. **Copy required files to your project:**
```bash
cp libnostr_core.a /path/to/your/project/
cp nostr_core/nostr_core.h /path/to/your/project/
```
2. **Link in your project:**
```bash
gcc your_code.c -L. -lnostr_core -lm -o your_program
```
### Source Integration
1. **Copy source files:**
```bash
cp -r nostr_core/ /path/to/your/project/
cp -r cjson/ /path/to/your/project/
```
2. **Include in your build:**
```bash
gcc your_code.c nostr_core/*.c cjson/cJSON.c -lm -o your_program
```
### Self-Contained Library
**x64 Library:** The `libnostr_core.a` file is completely self-contained with **no external dependencies**:
- ✅ **All OpenSSL code embedded**
- ✅ **No libwally required**
- ✅ **No system secp256k1 required**
- ✅ **Only needs math library (`-lm`)**
```bash
# x64 - This is all you need:
gcc your_app.c ./libnostr_core.a -lm -o your_app
```
**ARM64 Library:** The `libnostr_core_arm64.a` requires system OpenSSL:
```bash
# ARM64 - Requires OpenSSL libraries:
aarch64-linux-gnu-gcc your_app.c ./libnostr_core_arm64.a -lssl -lcrypto -lm -o your_app
```
## 🔧 Configuration
### Compile-Time Options
```c
// Enable debug output
#define NOSTR_DEBUG_ENABLED
// Crypto-only build (no networking)
#define NOSTR_CRYPTO_ONLY
// Enable specific NIPs
#define NOSTR_NIP04_ENABLED
#define NOSTR_NIP44_ENABLED
#define NOSTR_NIP13_ENABLED
```
### Build Flags
```bash
# Enable all logging
make LOGGING_FLAGS="-DENABLE_FILE_LOGGING -DENABLE_WEBSOCKET_LOGGING -DENABLE_DEBUG_LOGGING"
# Debug build
make debug
# ARM64 cross-compile
make arm64
```
## 🌐 Supported Platforms
- **Linux** (x86_64, ARM64)
- **macOS** (Intel, Apple Silicon)
- **Windows** (MinGW, MSYS2)
- **Embedded Systems** (resource-constrained environments)
## 📄 Documentation
- **[LIBRARY_USAGE.md](LIBRARY_USAGE.md)** - Detailed integration guide
- **[EXPORT_GUIDE.md](EXPORT_GUIDE.md)** - Library export instructions
- **[AUTOMATIC_VERSIONING.md](AUTOMATIC_VERSIONING.md)** - Version management
- **API Reference** - Complete documentation in `nostr_core/nostr_core.h`
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run the test suite: `./build.sh test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request
## 📈 Version History
Current version: **0.1.20**
The library uses automatic semantic versioning based on Git tags. Each build increments the patch version automatically.
**Recent Developments:**
- **OpenSSL Migration**: Transitioned from mbedTLS to OpenSSL for improved compatibility
- **NIP-05 Support**: DNS-based internet identifier verification
- **NIP-11 Support**: Relay information document fetching and parsing
- **Enhanced WebSocket**: OpenSSL-based TLS WebSocket communication
- **Production Ready**: Comprehensive test suite and error handling
**Version Timeline:**
- `v0.1.x` - Initial development releases
- Focus on core protocol implementation and OpenSSL-based crypto
- Full NIP-01, NIP-04, NIP-05, NIP-06, NIP-11, NIP-13, NIP-44 support
## 🐛 Troubleshooting
### Common Issues
**Build fails with secp256k1 errors:**
```bash
cd secp256k1
./autogen.sh
./configure --enable-module-schnorrsig --enable-module-ecdh
make
cd ..
./build.sh lib
```
**Library too large:**
The x64 library is intentionally large (~15MB) because it includes all secp256k1 cryptographic functions and OpenSSL for complete self-containment. The ARM64 library is smaller (~2.4MB) as it links against system OpenSSL.
**Linking errors:**
Make sure to include the math library:
```bash
gcc your_code.c ./libnostr_core.a -lm # Note the -lm flag
```
### Getting Help
- Check the `examples/` directory for working code
- Run `./build.sh test` to verify your environment
- Review the comprehensive API documentation in `nostr_core/nostr_core.h`
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **NOSTR Protocol** - The decentralized social media protocol
- **OpenSSL** - Production-grade cryptographic library and TLS implementation
- **secp256k1** - Bitcoin's elliptic curve library
- **cJSON** - Lightweight JSON parser
- **curl** - HTTP/HTTPS client library for NIP-05/NIP-11
- **NOSTR Community** - For protocol specification and feedback
---
**Built with ❤️ for the decentralized web**
*OpenSSL-based • Minimal dependencies • Production ready*

33
main.c
View File

@ -1,33 +0,0 @@
/*
* C Template - Main Example File
* This is a basic template file to demonstrate the project structure
*/
#include <stdio.h>
#include <stdlib.h>
// Include version header if it exists (will be auto-generated by build.sh)
#ifdef __has_include
#if __has_include("version.h")
#include "version.h"
#define HAS_VERSION
#endif
#endif
int main(void) {
printf("C Template Project\n");
printf("==================\n\n");
#ifdef HAS_VERSION
printf("Version: %s\n", get_version());
printf("Full Version: %s\n", get_version_full());
printf("Build Info: %s\n", get_build_info());
#else
printf("Version: Not available (run ./build.sh to generate version info)\n");
#endif
printf("\nThis is a template C project with automatic versioning.\n");
printf("Use ./build.sh to build the project and generate version information.\n");
return 0;
}