nostr_core_lib/examples/integration_example/README.md

NOSTR Core Integration Example

This directory contains a complete example showing how to integrate the NOSTR Core library into your own projects.

What This Example Demonstrates

• Library Initialization: Proper setup and cleanup of the NOSTR library
• Identity Management: Key generation, bech32 encoding, and format detection
• Event Creation: Creating and signing different types of NOSTR events
• Input Handling: Processing various input formats (mnemonic, hex, bech32)
• Utility Functions: Using helper functions for hex conversion and error handling
• CMake Integration: How to integrate the library in your CMake-based project

Building and Running

Method 1: Using CMake

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build
make

# Run the example
./my_nostr_app

Method 2: Manual Compilation

# Compile directly (assuming you're in the c_nostr root directory)
gcc -I. examples/integration_example/main.c nostr_core.c nostr_crypto.c cjson/cJSON.c -lm -o integration_example

# Run
./integration_example

Expected Output

The example will demonstrate:

1. Identity Management Demo

   • Generate a new keypair
   • Display keys in hex and bech32 format

2. Event Creation Demo

   • Create a text note event
   • Create a profile event
   • Display the JSON for both events

3. Input Handling Demo

   • Process different input formats
   • Show format detection and decoding

4. Utility Functions Demo

   • Hex conversion round-trip
   • Error message display

Integration Patterns

Pattern 1: CMake Find Package

If NOSTR Core is installed system-wide:

find_package(nostr_core REQUIRED)
target_link_libraries(your_app nostr_core::static)

Pattern 2: CMake Subdirectory

If NOSTR Core is a subdirectory of your project:

add_subdirectory(nostr_core)
target_link_libraries(your_app nostr_core_static)

Pattern 3: pkg-config

If using pkg-config:

find_package(PkgConfig REQUIRED)
pkg_check_modules(NOSTR_CORE REQUIRED nostr_core)
target_include_directories(your_app PRIVATE ${NOSTR_CORE_INCLUDE_DIRS})
target_link_libraries(your_app ${NOSTR_CORE_LIBRARIES})

Pattern 4: Direct Source Integration

Copy the essential files to your project:

cp nostr_core.{c,h} nostr_crypto.{c,h} your_project/src/
cp -r cjson/ your_project/src/

Then compile them with your project sources.

Code Structure

main.c Structure

The example is organized into clear demonstration functions:

• demo_identity_management() - Key generation and encoding
• demo_event_creation() - Creating different event types
• demo_input_handling() - Processing various input formats
• demo_utilities() - Using utility functions

Each function demonstrates specific aspects of the library while maintaining proper error handling and resource cleanup.

Key Integration Points

1. Initialization

   int ret = nostr_init();
   if (ret != NOSTR_SUCCESS) {
       // Handle error
   }
   

2. Resource Cleanup

   // Always clean up JSON objects
   cJSON_Delete(event);
   
   // Clean up library on exit
   nostr_cleanup();
   

3. Error Handling

   if (ret != NOSTR_SUCCESS) {
       printf("Error: %s\n", nostr_strerror(ret));
       return ret;
   }
   

Customization

You can modify this example for your specific needs:

• Change the app_config_t structure to match your application's configuration
• Add additional event types or custom event creation logic
• Integrate with your existing error handling and logging systems
• Add networking functionality using the WebSocket layer

Dependencies

This example requires:

• C99 compiler (gcc, clang)
• CMake 3.12+ (for CMake build)
• NOSTR Core library and its dependencies

Testing

You can test different input formats by passing them as command line arguments:

# Test with mnemonic
./my_nostr_app "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

# Test with hex private key
./my_nostr_app "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

# Test with bech32 nsec
./my_nostr_app "nsec1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Next Steps

After studying this example, you can:

1. Integrate the patterns into your own application
2. Explore the WebSocket functionality for relay communication
3. Add support for additional NOSTR event types
4. Implement your own identity persistence layer
5. Add networking and relay management features

For more examples, see the other files in the examples/ directory.