docs: Add documentation for resources, invoices, and messaging traits

Author: whoabuddy

docs/dao/traits/invoices.md

@@ -0,0 +1,84 @@
+# Invoices Trait
+
+The invoices trait defines the interface for processing payments for resources defined through the resources trait.
+
+## Interface
+
+```clarity
+(define-trait invoices (
+  (pay-invoice (uint (optional (buff 34))) (response uint uint))
+  (pay-invoice-by-resource-name ((string-utf8 50) (optional (buff 34))) (response uint uint))
+))
+```
+
+## Functions
+
+### Payment Processing
+
+#### pay-invoice
+Processes payment for a resource by ID.
+- Parameters:
+  - `uint`: Resource ID
+  - `memo`: Optional payment memo (34 bytes)
+- Access: Public
+- Returns: Invoice ID on success
+
+#### pay-invoice-by-resource-name
+Processes payment for a resource by name.
+- Parameters:
+  - `name`: Resource name
+  - `memo`: Optional payment memo (34 bytes)
+- Access: Public
+- Returns: Invoice ID on success
+
+## Implementation Requirements
+
+1. Verify resource exists and is enabled
+2. Process payment transfer
+3. Generate unique invoice ID
+4. Track payment status
+5. Handle payment memos
+6. Emit payment events
+
+## Usage Pattern
+
+Implementations should:
+1. Validate resource status
+2. Process payment atomically
+3. Generate sequential invoice IDs
+4. Log payment details
+
+Example implementation:
+```clarity
+(define-public (pay-invoice-by-resource-name 
+    (name (string-utf8 50))
+    (memo (optional (buff 34))))
+  (let (
+    (resource (unwrap! (get-resource-by-name name) ERR_NOT_FOUND))
+    (price (get price resource))
+  )
+    ;; Verify resource enabled
+    (asserts! (get enabled resource) ERR_DISABLED)
+    
+    ;; Process payment
+    (try! (stx-transfer? price tx-sender payment-address))
+    
+    ;; Generate invoice
+    (let ((invoice-id (generate-invoice-id)))
+      ;; Log payment
+      (print {
+        notification: "payment-processed",
+        payload: {
+          resource: name,
+          price: price,
+          payer: tx-sender,
+          invoiceId: invoice-id,
+          memo: memo
+        }
+      })
+      
+      (ok invoice-id)
+    )
+  )
+)
+```

docs/dao/traits/messaging.md

@@ -0,0 +1,62 @@
+# Messaging Trait
+
+The messaging trait defines the interface for sending on-chain messages up to 1MB in size.
+
+## Interface
+
+```clarity
+(define-trait messaging (
+  (send ((string-ascii 1048576) bool) (response bool uint))
+))
+```
+
+## Functions
+
+### send
+Sends an on-chain message.
+- Parameters:
+  - `message`: ASCII message content (max 1MB)
+  - `isFromDao`: Whether message is from DAO
+- Access: Public for regular messages, DAO/extension only for DAO messages
+- Returns: Success/failure response
+
+## Implementation Requirements
+
+1. Validate message size (≤ 1MB)
+2. Enforce DAO authorization for DAO messages
+3. Track message history
+4. Handle message encoding
+5. Emit message events
+
+## Usage Pattern
+
+Implementations should:
+1. Verify message size
+2. Check authorization for DAO messages
+3. Log message details
+4. Handle errors gracefully
+
+Example implementation:
+```clarity
+(define-public (send (message (string-ascii 1048576)) (isFromDao bool))
+  (begin
+    ;; Check DAO authorization if needed
+    (if isFromDao
+      (try! (is-dao-or-extension))
+      true
+    )
+    
+    ;; Log message
+    (print {
+      notification: "message-sent",
+      payload: {
+        sender: tx-sender,
+        isFromDao: isFromDao,
+        message: message
+      }
+    })
+    
+    (ok true)
+  )
+)
+```

docs/dao/traits/resources.md

@@ -0,0 +1,99 @@
+# Resources Trait
+
+The resources trait defines the interface for managing payable resources with configurable pricing and descriptions.
+
+## Interface
+
+```clarity
+(define-trait resources (
+  (set-payment-address (principal) (response bool uint))
+  (add-resource ((string-utf8 50) (string-utf8 255) uint (optional (string-utf8 255))) (response uint uint))
+  (toggle-resource (uint) (response bool uint))
+  (toggle-resource-by-name ((string-utf8 50)) (response bool uint))
+))
+```
+
+## Functions
+
+### Configuration
+
+#### set-payment-address
+Sets the payment recipient for resource invoices.
+- Parameters:
+  - `principal`: Payment recipient address
+- Access: DAO/extension only
+- Returns: Success/failure response
+
+### Resource Management
+
+#### add-resource
+Creates a new payable resource.
+- Parameters:
+  - `name`: Resource name (max 50 chars)
+  - `description`: Resource description (max 255 chars)
+  - `price`: Price in microSTX
+  - `metadata`: Optional additional data (max 255 chars)
+- Access: DAO/extension only
+- Returns: Resource ID on success
+
+#### toggle-resource
+Enables/disables a resource by ID.
+- Parameters:
+  - `uint`: Resource ID
+- Access: DAO/extension only
+- Returns: Success/failure response
+
+#### toggle-resource-by-name
+Enables/disables a resource by name.
+- Parameters:
+  - `name`: Resource name
+- Access: DAO/extension only
+- Returns: Success/failure response
+
+## Implementation Requirements
+
+1. Maintain unique resource names
+2. Track resource enabled/disabled status
+3. Validate input parameters
+4. Enforce DAO/extension-only access
+5. Emit events for state changes
+
+## Usage Pattern
+
+Implementations should:
+1. Verify resource name uniqueness
+2. Validate price > 0
+3. Track resource status
+4. Log all changes
+
+Example implementation:
+```clarity
+(define-public (add-resource (name (string-utf8 50)) 
+                            (description (string-utf8 255))
+                            (price uint)
+                            (metadata (optional (string-utf8 255))))
+  (begin
+    ;; Check authorization
+    (try! (is-dao-or-extension))
+    
+    ;; Validate inputs
+    (asserts! (> price u0) ERR_INVALID_PRICE)
+    (asserts! (not (resource-exists name)) ERR_NAME_EXISTS)
+    
+    ;; Save resource
+    (try! (save-resource name description price metadata))
+    
+    ;; Log creation
+    (print {
+      notification: "resource-added",
+      payload: {
+        name: name,
+        price: price,
+        description: description
+      }
+    })
+    
+    (ok true)
+  )
+)
+```