# Vector SDK

The Vector Bot Library is a Rust-based library for creating and managing Vector Bots that can send and receive private messages using the Nostr protocol. This library provides a structured and modular approach to building bots with configurable metadata and client settings.

## Features

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-robot">:robot:</i></h4></td><td><strong>Vector Bots</strong></td><td>with custom metadata.</td><td><a href="/files/7XsNFQ1ZJ2HlTZ9k6KrQ">/files/7XsNFQ1ZJ2HlTZ9k6KrQ</a></td><td></td><td></td></tr><tr><td><h4><i class="fa-envelope-open-text">:envelope-open-text:</i></h4></td><td><strong>Send/Receive Files</strong></td><td>Private messages &#x26; files.</td><td><a href="/files/iPYlZKAFODyyg31M4uFZ">/files/iPYlZKAFODyyg31M4uFZ</a></td><td></td><td></td></tr><tr><td><h4><i class="fa-bell">:bell:</i></h4></td><td><strong>Custom Notifications</strong></td><td>for Gift Wrap events.</td><td><a href="/files/qtxrGVaKW5EZ3ZbxMlyi">/files/qtxrGVaKW5EZ3ZbxMlyi</a></td><td></td><td></td></tr><tr><td><h4><i class="fa-onion">:onion:</i></h4></td><td><strong>Proxy Settings</strong></td><td>Configure for .onion relays.</td><td><a href="/files/g5Jq885MDfM8LCsV3xFV">/files/g5Jq885MDfM8LCsV3xFV</a></td><td></td><td></td></tr><tr><td><h4><i class="fa-network-wired">:network-wired:</i></h4></td><td><strong>Relays</strong></td><td>Add and manage.</td><td><a href="/files/4yXYwZDhsN8E6p4ZiXm6">/files/4yXYwZDhsN8E6p4ZiXm6</a></td><td></td><td></td></tr><tr><td><h4><i class="fa-cubes">:cubes:</i></h4></td><td><strong>Modular</strong></td><td>Easy ext. &#x26; maintenance.</td><td><a href="/files/bdDlrLwCUIkMUZSuLeGB">/files/bdDlrLwCUIkMUZSuLeGB</a></td><td></td><td></td></tr></tbody></table>

* Create Vector Bots with customizable metadata
* Send and receive private messages and files
* Handle notifications for gift wrap events
* Configure proxy settings for .onion relays
* Add and manage relays
* Modular architecture for easy extension and maintenance
* Message Layer Security (MLS) for group messaging
* Typing indicators for real-time feedback
* Reaction support for messages
* File uploads with progress tracking
* Automatic failover for media servers

***

## MLS Implementation Status

The Vector SDK includes **Message Layer Security (MLS)** support for group messaging. The following MLS features are currently implemented and ready for use:

{% tabs fullWidth="false" %}
{% tab title="Implemented Features" %}

<div align="left"><figure><img src="/files/JwhGlFC0s3Zm8FuyQXf1" alt="Vector Icon - Checkmark" width="128"><figcaption></figcaption></figure></div>

### **Implemented Features:**

* Group joining via welcome events
* Group message sending and processing
* Group typing indicators
* Group file attachments
* Group reactions
* Persistent SQLite-backed storage for group state
  {% endtab %}

{% tab title="Placeholder Functions" %}

<div align="left"><figure><img src="/files/mJdGWVHmkYGwCm2hf3OK" alt="Vector Icon - Warning" width="128"><figcaption></figcaption></figure></div>

### **Placeholder Functions (Not Yet Implemented):**&#x20;

The following MLS functions exist as stubs and will be implemented in future versions when needed:

* `create_group()` - Group creation functionality
* `add_member_device()` - Adding members to groups
* `leave_group()` - Leaving groups
* `remove_member_device_from_group()` - Removing members
* `send_group_message()` - Direct group message sending (use `Group::send_group_message()` instead)

These placeholder functions are available in the API but will return errors if called. They are included to provide a complete API surface for future expansion.
{% endtab %}
{% endtabs %}

***

## Documentation

For comprehensive documentation, see:

* [**CONTRIBUTING**](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/contributing) - Development guidelines and contribution process
* [**SECURITY**](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/security) - Security features, best practices, and threat model
* [**ADVANCED**](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/advanced) - Advanced features including MLS, typing indicators, and debugging
* [**TROUBLESHOOTING**](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/troubleshooting) - Common issues and solutions
* [**CHANGELOG**](changelog.mdhttps://github.com/VectorPrivacy/Vector-SDK/blob/mls-groups/CHANGELOG.md) - Release history and changes

***

## Examples

For practical examples and working code demonstrations, see the [Vector-SDK-Example](https://github.com/Luke-Larsen/Vector-SDK-Example) repository, which contains:

* Basic bot setup examples
* Direct messaging implementations
* Group messaging examples
* File handling demonstrations
* Advanced use cases
* Complete working applications

***

## Architecture

The library is organized into several modules, each responsible for a specific aspect of the bot's functionality:

1. [**VectorBot**](/vector-privacy/vector-sdk/basics/components.md#vectorbot): The main struct representing the bot, containing metadata and client configuration.
2. [**Channel**](/vector-privacy/vector-sdk/basics/components.md#channel): A struct for managing communication with specific recipients.
3. [**Client**](/vector-privacy/vector-sdk/basics/components.md#client): Functions for building and configuring the Nostr client.
4. [**Metadata**](/vector-privacy/vector-sdk/basics/components.md#metadata): Functions for creating and managing bot metadata.
5. [**Subscription**](/vector-privacy/vector-sdk/basics/components.md#subscription): Functions for setting up event subscriptions.
6. [**Crypto**](/vector-privacy/vector-sdk/basics/components.md#crypto): Functions for encryption and decryption.
7. [**Upload**](/vector-privacy/vector-sdk/basics/components.md#upload): Functions for handling file uploads.

### High Level Architecture

```
+---------------------+
|     VectorBot       |
|---------------------|
| - keys              |
| - name              |
| - display_name      |
| - about             |
| - picture           |
| - banner            |
| - nip05             |
| - lud16             |
| - client            |
|---------------------|
| + quick()           |
| + new()             |
| + get_chat()        |
+---------------------+
          |
          v
+---------------------+
|      Channel        |
|---------------------|
| - recipient         |
| - base_bot          |
|---------------------|
| + new()             |
| + send_private_msg()|
+---------------------+

+---------------------+
|      Client        |
|---------------------|
| + build_client()   |
+---------------------+

+---------------------+
|     Metadata       |
|---------------------|
| + create_metadata()|
+---------------------+

+---------------------+
|   Subscription     |
|---------------------|
| + create_gift_wrap_|
|   subscription()    |
+---------------------+

+---------------------+
|      Crypto        |
|---------------------|
| + generate_encryption_params() |
| + encrypt_data()   |
+---------------------+

+---------------------+
|      Upload        |
|---------------------|
| + upload_data_with_progress() |
+---------------------+
```

For more detailed information about the architecture and advanced features, see [ADVANCED.md](https://github.com/VectorPrivacy/Vector-SDK/blob/mls-groups/ADVANCED.md).

***

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/VectorPrivacy/Vector-SDK/blob/mls-groups/LICENSE) file for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.