diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e19a704
--- /dev/null
+++ b/README.md
@@ -0,0 +1,145 @@
+# Token Validation Smart Contract
+
+## Overview
+This smart contract implements a token validation system on the Stacks blockchain using Clarity. It provides a secure way to validate token principals with built-in error handling and response management.
+
+## Features
+- Principal-based token validation
+- Comprehensive error handling
+- Multiple validation approaches
+- Transaction sender verification
+- Configurable error responses
+
+## Contract Components
+
+### Error Constants
+```clarity
+ERR-INVALID-TOKEN (err u1)    // Used when token validation fails
+ERR-VALIDATION-FAILED (err u2) // Used for general validation failures
+```
+
+### Core Functions
+
+#### `comprehensive-token-validation`
+Private function that handles the core validation logic.
+```clarity
+(define-private (comprehensive-token-validation (token principal)))
+```
+- **Parameters**: 
+  - `token`: Principal to validate
+- **Returns**: Response containing either:
+  - Success: Original token principal
+  - Error: ERR-INVALID-TOKEN
+
+#### `process-new-token`
+Public function implementing the primary validation approach.
+```clarity
+(define-public (process-new-token (new-token principal)))
+```
+- **Parameters**:
+  - `new-token`: Principal to process
+- **Returns**: Response containing either:
+  - Success: u1
+  - Error: ERR-VALIDATION-FAILED
+
+#### `process-new-token-alt`
+Alternative public function with direct matching approach.
+```clarity
+(define-public (process-new-token-alt (new-token principal)))
+```
+- **Parameters**:
+  - `new-token`: Principal to process
+- **Returns**: Response containing either:
+  - Success: u1
+  - Error: ERR-VALIDATION-FAILED
+
+## Usage
+
+### Basic Implementation
+```clarity
+;; Call the process-new-token function
+(contract-call? .token-contract process-new-token tx-sender)
+```
+
+### Alternative Approach
+```clarity
+;; Call the alternative processing function
+(contract-call? .token-contract process-new-token-alt tx-sender)
+```
+
+## Security Considerations
+
+### Principal Validation
+- The contract validates principals against the transaction sender
+- Additional validation rules can be implemented in the `comprehensive-token-validation` function
+- All error cases are explicitly handled
+
+### Error Handling
+- Uses explicit error codes for different failure scenarios
+- Implements match expressions for proper error propagation
+- Maintains type safety throughout the contract
+
+## Development
+
+### Prerequisites
+- Clarity CLI
+- Stacks blockchain node (for testing)
+- Clarity VS Code extension (recommended)
+
+### Testing
+1. Clone the repository
+2. Deploy the contract to a local Stacks node
+3. Run test cases against the deployed contract
+
+### Deployment
+1. Build the contract:
+```bash
+clarinet build
+```
+
+2. Deploy to testnet:
+```bash
+clarinet deploy --testnet
+```
+
+3. Deploy to mainnet:
+```bash
+clarinet deploy --mainnet
+```
+
+## Customization
+
+### Adding Custom Validation Rules
+Modify the `comprehensive-token-validation` function to add additional validation:
+
+```clarity
+(define-private (comprehensive-token-validation (token principal))
+    (if (and
+            (is-eq token tx-sender)
+            ;; Add additional validation here
+            (is-eq token contract-owner)
+        )
+        (ok token)
+        ERR-INVALID-TOKEN))
+```
+
+### Modifying Error Codes
+Add new error constants as needed:
+```clarity
+(define-constant ERR-CUSTOM-ERROR (err u3))
+```
+
+## Best Practices
+
+1. Always use explicit error handling
+2. Validate all inputs thoroughly
+3. Keep track of response types
+4. Use meaningful error codes
+5. Document function behavior
+
+## Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Submit a pull request
+4. Ensure all tests pass
+
diff --git a/contracts/real.clar b/contracts/real.clar
index e44b19a..0fc7115 100644
--- a/contracts/real.clar
+++ b/contracts/real.clar
@@ -1,15 +1,35 @@
+;; Define error codes
+(define-constant ERR-INVALID-TOKEN (err u1))
+(define-constant ERR-VALIDATION-FAILED (err u2))
 
-;; real
-;; <add a description here>
+;; Token validation utility function with explicit response type
+(define-private (comprehensive-token-validation (token principal))
+    ;; For demonstration, validating if principal is not null
+    ;; In a real implementation, you would add more validation logic
+    (if (is-eq token tx-sender)  ;; Example validation comparing with tx-sender
+        (ok token)
+        ERR-INVALID-TOKEN))
 
-;; constants
-;;
+;; First approach: Direct validation with match
+(define-public (process-new-token (new-token principal))
+    (let 
+        (
+            ;; Store the validation result
+            (validation-result (comprehensive-token-validation new-token))
+        )
+        ;; Check the validation result
+        (match validation-result
+            success (ok u1)
+            error ERR-VALIDATION-FAILED)
+    )
+)
 
-;; data maps and vars
-;;
-
-;; private functions
-;;
-
-;; public functions
-;;
+;; Second approach: Alternative validation method
+(define-public (process-new-token-alt (new-token principal))
+    (begin
+        ;; Validate token with direct matching
+        (match (comprehensive-token-validation new-token)
+            success (ok u1)
+            error ERR-VALIDATION-FAILED)
+    )
+)git 
\ No newline at end of file