From 22a0f47707cef65648a0c1c998a7bee892942232 Mon Sep 17 00:00:00 2001 From: Your Name Date: Thu, 14 Aug 2025 15:38:15 -0400 Subject: [PATCH] cleanup --- README.md | 484 ------------------------------------------------------ main.c | 33 ---- 2 files changed, 517 deletions(-) delete mode 100644 main.c diff --git a/README.md b/README.md index d86a2b1..e69de29 100644 --- a/README.md +++ b/README.md @@ -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 - -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* diff --git a/main.c b/main.c deleted file mode 100644 index f81b3ef..0000000 --- a/main.c +++ /dev/null @@ -1,33 +0,0 @@ -/* - * C Template - Main Example File - * This is a basic template file to demonstrate the project structure - */ - -#include -#include - -// 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; -}