SecureChat - Decentralized Messaging Protocol

Overview

SecureChat is a privacy-focused blockchain messaging smart contract built on the Stacks blockchain using Clarity. It enables secure, censorship-resistant peer-to-peer communication with end-to-end encryption support, user autonomy, and comprehensive contact management.

Version: 2.0.0
Language: Clarity (Stacks Blockchain)

Features

Core Messaging

• Decentralized Message Storage: All messages are stored on-chain with complete ownership and control
• End-to-End Encryption Support: Flag messages as encrypted with support for custom encryption keys
• Conversation Threading: Organize messages into multi-participant threads
• Message Indexing: Efficient retrieval of sent and received messages with pagination support
• Delivery Status Tracking: Track message delivery and status

User Management

• User Profiles: Create and manage on-chain identities with custom usernames
• Privacy Levels: Set security/privacy levels (0-10 scale) for granular control
• Verification System: Mark accounts as verified for trust establishment
• Encryption Key Storage: Store public encryption keys for secure communication

Contact & Blocking System

• Contact Management: Add contacts with custom nicknames and trust scores (0-10 scale)
• Trust Scoring: Rate contacts based on reliability and trustworthiness
• Block/Unblock Users: Prevent unwanted communication with detailed block reasons
• Last Interaction Tracking: Monitor when you last communicated with each contact

Statistics & Analytics

• Message Counters: Track total messages sent, received, and overall count
• User Activity Metrics: Monitor individual user engagement
• Thread Analytics: View thread activity and participant counts

Constants & Limits

Parameter	Limit	Description
Message Content	1000 characters	Maximum ASCII message length
Username	50 characters	Maximum username length
Nickname	50 characters	Maximum contact nickname length
Encryption Key	100 characters	Maximum encryption key length
Block Reason	100 characters	Maximum block reason length
Trust Score	0-10	User trust rating range
Privacy Level	0-10	Security level range
Thread Participants	10 users	Maximum participants per thread

Key Functions

Messaging

send-message

Send a message to another user.

(send-message 
    (recipient principal) 
    (content (string-ascii 1000)) 
    (encrypted bool) 
    (thread-id (optional uint))
    (priority uint))

Parameters:

• recipient: The receiving user's principal address
• content: Message content (max 1000 characters)
• encrypted: Flag indicating if message is encrypted
• thread-id: Optional conversation thread ID
• priority: Message priority level

Returns: (ok message-id) on success

Validations:

• Sender and recipient must be different users
• Content must not exceed 1000 characters
• Recipient must not have blocked sender
• Protocol must be active
• Thread ID must be valid if provided

get-chat-history

Retrieve message history between two users with pagination.

(get-chat-history 
    (user1 principal) 
    (user2 principal) 
    (start-idx uint) 
    (limit uint))

Access: Only authorized participants can view chat history

User Profile Management

create-user-profile

Create or update your user profile.

(create-user-profile 
    (username (string-ascii 50)) 
    (encryption-key (optional (string-ascii 100)))
    (privacy-level uint))

Parameters:

• username: Display name (max 50 characters)
• encryption-key: Optional public encryption key
• privacy-level: Security level (0-10)

Contact Management

add-contact

Add a user to your contact list.

(add-contact 
    (contact principal) 
    (nickname (string-ascii 50))
    (trust-score uint))

Parameters:

• contact: User's principal address
• nickname: Custom display name
• trust-score: Trust rating (0-10)

remove-contact

Remove a user from your contact list.

(remove-contact (contact principal))

Blocking System

block-user

Block a user from sending you messages.

(block-user 
    (target principal) 
    (reason (string-ascii 100)))

Parameters:

• target: User to block
• reason: Explanation for blocking (required, max 100 characters)

unblock-user

Unblock a previously blocked user.

(unblock-user (target principal))

Thread Management

create-conversation

Create a multi-participant conversation thread.

(create-conversation (participants (list 10 principal)))

Parameters:

• participants: List of up to 10 principals

Returns: (ok thread-id) on success

Read-Only Functions

Query Functions

• get-message: Retrieve a specific message by ID
• get-user-profile: Get user profile information
• is-user-blocked: Check if a user is blocked
• get-contact-info: Get contact details
• get-total-messages: Get total message count in the protocol
• get-user-statistics: Get user's message statistics (sent/received/total)
• get-user-message-by-index: Retrieve user messages by index
• is-protocol-active: Check if protocol is operational
• get-thread-info: Get conversation thread details
• get-protocol-info: Get system-wide information

Error Codes

Code	Constant	Description
200	ERR-UNAUTHORIZED-ACTION	User not authorized for this action
201	ERR-MESSAGE-NOT-FOUND	Message does not exist
202	ERR-INVALID-RECIPIENT	Invalid or blocked recipient
203	ERR-CONTENT-TOO-LARGE	Content exceeds size limit
204	ERR-RECIPIENT-ALREADY-BLOCKED	User is already blocked
205	ERR-RECIPIENT-NOT-BLOCKED	User is not blocked
206	ERR-CANNOT-TARGET-SELF	Cannot perform action on yourself
207	ERR-INVALID-PAGINATION	Invalid pagination parameters
208	ERR-INVALID-PARAMETER	Invalid function parameter
209	ERR-INVALID-THREAD	Thread does not exist
210	ERR-INVALID-TRUST-SCORE	Trust score outside valid range
211	ERR-INVALID-PRIVACY-LEVEL	Privacy level outside valid range

Data Privacy & Security

On-Chain Storage

All messages and user data are stored on the blockchain. This provides:

• Immutability: Messages cannot be altered once sent
• Transparency: All data is publicly readable on the blockchain
• Censorship Resistance: No central authority can delete messages

Privacy Considerations

⚠️ Important: While the contract supports encryption flags and key storage, the actual message content is stored as plain ASCII text on-chain. For true privacy:

1. Client-Side Encryption: Encrypt messages before sending them to the contract
2. Key Exchange: Use the stored encryption keys for secure key exchange
3. Off-Chain Decryption: Decrypt messages client-side after retrieval

Encryption Workflow Example

1. User A retrieves User B's encryption-key from their profile
2. User A encrypts message content using User B's public key
3. User A sends encrypted content via send-message with encrypted=true
4. User B retrieves encrypted message from blockchain
5. User B decrypts using their private key client-side

Administrative Functions

set-protocol-status

Enable or disable the entire protocol (owner only).

(set-protocol-status (enabled bool))

Access: Contract owner only

Use Cases

1. Decentralized Messaging Apps: Build censorship-resistant chat applications
2. Blockchain-Based Support Systems: On-chain customer support with message history
3. DAO Communications: Transparent governance discussions
4. Encrypted Coordination: Secure team collaboration with verifiable message trails
5. Social Verification Systems: Trust-scored contact networks

Deployment

The contract deploys with:

• Protocol status: Active
• Message counter: 0
• Contract owner: Deployer's principal

Development Considerations

Gas Optimization

• Use pagination when retrieving message history
• Batch contact additions when possible
• Consider message frequency for cost management

Integration Tips

• Store encryption keys off-chain for added security
• Implement client-side encryption libraries
• Cache user profiles to reduce read calls
• Use indexing for efficient message retrieval

Future Enhancements

Potential improvements for future versions:

• Message editing and deletion mechanisms
• Enhanced thread management (add/remove participants)
• Read receipts and typing indicators
• Message reactions and attachments
• Group admin controls
• Message forwarding capabilities