voidpy 1.0.1
Void Execution Engine - Translates Python to Logic States
License: MIT
Requires Python: >=3.6
Keywords: encryption, obfuscation, bytecode, void, logic-states, protection

# voidpy

Void Execution Engine - Translates Python to Logic States

Developer: **MERO** | Telegram: [@QP4RM](https://t.me/QP4RM)

---

## Installation

```bash
pip install voidpy
```

---

## What is voidpy?

voidpy is a revolutionary Python protection system that does NOT work like traditional obfuscators.

Traditional obfuscators:
- Rename variables
- Add junk code
- Encode strings
- Still produce executable Python

voidpy is different:
- Completely translates Python to internal Logic States
- The output contains NO Python code
- The output contains NO Python bytecode
- The output contains NO readable patterns
- Execution happens through voidpy engine only

---

## How It Works

```
Python Code -> AST Parser -> Logic States -> Fake States -> Fragmentation -> Shuffle -> Multi-Layer Encryption -> .void
```

The .void file:
- Contains only MERO_* values
- Contains only obfuscated state machine
- Contains only encrypted binary data
- Cannot be decompiled
- Cannot be reverse engineered
- Can ONLY be executed by voidpy engine

---

## Core Features

### 1. Logic State Translation
Python code is NOT encrypted - it is TRANSLATED to a completely different language.

### 2. Fake States (75%+)
75% of states in the output are fake (dead states). They:
- Do nothing
- Look real
- Confuse reverse engineering
- Make analysis impossible

### 3. Logic Fragmentation
Single operations are split across multiple states. A simple addition becomes 4+ separate states scattered throughout the file.

### 4. Multi-Layer Encryption
Each layer applies MERO-exclusive algorithms:
- MERO Transform (custom byte manipulation)
- VOID Cipher (stream cipher)
- QP4RM Cipher (substitution cipher)
- S-Box transformation
- Bit rotation
- Block scrambling
- Diffusion layer

### 5. API Virtualization
No direct Python calls. All operations go through:
- MERO_PRINT instead of print
- MERO_IO instead of open
- MERO_CALL instead of function calls

### 6. MERO Protection
If someone tries to analyze the encrypted data, they only find:
- MERO_FUK
- MERO_NIL
- MERO_DEAD
- MERO_VOID
- MERO_TRAP
- QP4RM_X
- And other meaningless values

---

## Security Architecture

### Layer 1: AST Translation
Python -> Abstract Syntax Tree -> Logic States

### Layer 2: Obfuscation
Variable names -> V000, V001, V002...
Function names -> F000, F001, F002...
All identifiers -> Unreadable IDs

### Layer 3: Fake Injection
Real states: 25%
Fake states: 75%
Pattern: Indistinguishable

### Layer 4: Fragmentation
1 operation -> 4+ fragments
Fragments -> Scattered randomly
Logic -> Impossible to trace

### Layer 5: Shuffle
Original order -> Destroyed
Execution order -> Only known to engine
Analysis -> Impossible

### Layer 6: Encryption
16 rounds of MERO algorithms:
- MERO Transform
- S-Box substitution
- Bit rotation
- Byte permutation
- VOID Cipher
- QP4RM Cipher
- Block scrambling
- Diffusion

### Layer 7: Padding
Random padding added
Size analysis -> Prevented

---

## Why voidpy is Different

### Traditional Protection
```
Original Python -> Encoded Python -> Decode -> Execute
```
Problem: Decoding step exposes original code

### voidpy Protection
```
Original Python -> Logic States -> Execute Directly
```
Solution: No decoding step, no exposure

The voidpy engine:
- Does NOT decode to Python
- Does NOT decode to bytecode
- Executes Logic States directly
- Like CPU executes machine code

---

## Compatibility

Works on:
- Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
- Linux
- Windows
- macOS
- Termux (Android terminal)
- Pydroid (Android Python IDE)

---

## CLI Commands

### All Commands

| Command | Aliases | Description |
|---------|---------|-------------|
| `encrypt` | `e`, `p`, `l`, `lock`, `protect` | Encrypt Python file |
| `run` | `r`, `x`, `g`, `exec`, `go` | Run encrypted .void file |
| `inline` | `i`, `t`, `q`, `test`, `quick` | Encrypt and run inline code |
| `check` | `c`, `verify` | Verify .void file integrity |
| `batch` | `b`, `all` | Encrypt multiple files |
| `version` | `v`, `ver` | Show version |
| `on` | `dev`, `tg`, `telegram`, `mero`, `contact` | Open developer contact |
| `info` | `about`, `a` | Show detailed info |
| `help` | `h` | Show help |

### Encrypt a file

```bash
voidpy encrypt script.py
```

```bash
voidpy encrypt script.py -o output.void
```

```bash
voidpy encrypt script.py -o output.void -l 5
```

### Run encrypted file

```bash
voidpy run output.void
```

### Quick inline test

```bash
voidpy inline "print('Hello')"
```

### Check file integrity

```bash
voidpy check output.void
```

### Batch encrypt

```bash
voidpy batch file1.py file2.py file3.py
```

```bash
voidpy batch *.py -l 5
```

### Developer contact

```bash
voidpy on
```

### Options

| Option | Description |
|--------|-------------|
| `-o` | Output file path |
| `-l` | Encryption layers (1-10, default: 3) |
| `-h` | Show help |

---

## Quick Reference

| Command | Description |
|---------|-------------|
| `voidpy e file.py` | Encrypt Python file |
| `voidpy e file.py -o out.void` | Encrypt with custom output |
| `voidpy e file.py -l 7` | Encrypt with 7 layers |
| `voidpy r file.void` | Run encrypted file |
| `voidpy i "code"` | Encrypt and run inline |
| `voidpy c file.void` | Check file integrity |
| `voidpy b *.py` | Batch encrypt |
| `voidpy on` | Developer contact |

---

## Script Examples (30+)

### Example 1: Hello World

```python
# hello.py
print("Hello, World!")
```

```bash
voidpy e hello.py
voidpy r hello.void
```

### Example 2: Variables

```python
# vars.py
name = "MERO"
age = 25
active = True
print(f"Name: {name}, Age: {age}, Active: {active}")
```

```bash
voidpy e vars.py -l 3
voidpy r vars.void
```

### Example 3: Math Operations

```python
# math_ops.py
a = 10
b = 5
print(f"Add: {a + b}")
print(f"Sub: {a - b}")
print(f"Mul: {a * b}")
print(f"Div: {a / b}")
print(f"Mod: {a % b}")
print(f"Pow: {a ** b}")
```

```bash
voidpy e math_ops.py
voidpy r math_ops.void
```

### Example 4: String Operations

```python
# strings.py
text = "voidpy protection"
print(text.upper())
print(text.lower())
print(text.title())
print(text.replace("protection", "security"))
print(len(text))
print(text[0:6])
```

```bash
voidpy e strings.py -l 5
voidpy r strings.void
```

### Example 5: Lists

```python
# lists.py
numbers = [1, 2, 3, 4, 5]
print(numbers)
numbers.append(6)
print(numbers)
print(sum(numbers))
print(max(numbers))
print(min(numbers))
```

```bash
voidpy e lists.py
voidpy r lists.void
```

### Example 6: Dictionaries

```python
# dicts.py
user = {"name": "MERO", "role": "Developer", "active": True}
print(user["name"])
print(user.get("role"))
user["level"] = 100
print(user)
for key, value in user.items():
    print(f"{key}: {value}")
```

```bash
voidpy e dicts.py -l 4
voidpy r dicts.void
```

### Example 7: If/Else Conditions

```python
# conditions.py
score = 85
if score >= 90:
    print("A")
elif score >= 80:
    print("B")
elif score >= 70:
    print("C")
else:
    print("F")
```

```bash
voidpy e conditions.py
voidpy r conditions.void
```

### Example 8: For Loops

```python
# for_loop.py
for i in range(5):
    print(f"Iteration {i}")

fruits = ["apple", "banana", "cherry"]
for fruit in fruits:
    print(f"I like {fruit}")
```

```bash
voidpy e for_loop.py -l 3
voidpy r for_loop.void
```

### Example 9: While Loops

```python
# while_loop.py
count = 0
while count < 5:
    print(f"Count: {count}")
    count += 1
print("Done!")
```

```bash
voidpy e while_loop.py
voidpy r while_loop.void
```

### Example 10: Functions

```python
# functions.py
def greet(name):
    return f"Hello, {name}!"

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

print(greet("MERO"))
print(add(10, 20))
print(multiply(5, 6))
```

```bash
voidpy e functions.py -l 5
voidpy r functions.void
```

### Example 11: Default Arguments

```python
# defaults.py
def power(base, exp=2):
    return base ** exp

print(power(5))
print(power(2, 10))
print(power(3, 3))
```

```bash
voidpy e defaults.py
voidpy r defaults.void
```

### Example 12: Multiple Returns

```python
# multi_return.py
def get_stats(numbers):
    return min(numbers), max(numbers), sum(numbers)

nums = [1, 2, 3, 4, 5]
minimum, maximum, total = get_stats(nums)
print(f"Min: {minimum}, Max: {maximum}, Sum: {total}")
```

```bash
voidpy e multi_return.py -l 4
voidpy r multi_return.void
```

### Example 13: Nested Loops

```python
# nested.py
for i in range(3):
    for j in range(3):
        print(f"({i}, {j})")
```

```bash
voidpy e nested.py
voidpy r nested.void
```

### Example 14: List Comprehension

```python
# comprehension.py
squares = [x**2 for x in range(10)]
print(squares)

evens = [x for x in range(20) if x % 2 == 0]
print(evens)
```

```bash
voidpy e comprehension.py -l 3
voidpy r comprehension.void
```

### Example 15: Lambda Functions

```python
# lambda.py
double = lambda x: x * 2
square = lambda x: x ** 2
add = lambda a, b: a + b

print(double(5))
print(square(4))
print(add(3, 7))
```

```bash
voidpy e lambda.py -l 5
voidpy r lambda.void
```

### Example 16: Recursion

```python
# recursion.py
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(f"5! = {factorial(5)}")
print(f"Fib(10) = {fibonacci(10)}")
```

```bash
voidpy e recursion.py -l 5
voidpy r recursion.void
```

### Example 17: String Formatting

```python
# formatting.py
name = "MERO"
age = 25
balance = 1234.56

print(f"Name: {name}")
print(f"Age: {age:03d}")
print(f"Balance: ${balance:.2f}")
print("{} is {} years old".format(name, age))
```

```bash
voidpy e formatting.py
voidpy r formatting.void
```

### Example 18: Boolean Logic

```python
# boolean.py
a = True
b = False

print(f"a AND b: {a and b}")
print(f"a OR b: {a or b}")
print(f"NOT a: {not a}")
print(f"a XOR b: {a != b}")
```

```bash
voidpy e boolean.py -l 3
voidpy r boolean.void
```

### Example 19: Comparison Operators

```python
# compare.py
x = 10
y = 20

print(f"x == y: {x == y}")
print(f"x != y: {x != y}")
print(f"x < y: {x < y}")
print(f"x > y: {x > y}")
print(f"x <= y: {x <= y}")
print(f"x >= y: {x >= y}")
```

```bash
voidpy e compare.py
voidpy r compare.void
```

### Example 20: Tuples

```python
# tuples.py
point = (10, 20)
colors = ("red", "green", "blue")

print(point)
print(colors[0])
print(len(colors))

x, y = point
print(f"X: {x}, Y: {y}")
```

```bash
voidpy e tuples.py -l 4
voidpy r tuples.void
```

### Example 21: Sets

```python
# sets.py
a = {1, 2, 3, 4}
b = {3, 4, 5, 6}

print(f"Union: {a | b}")
print(f"Intersection: {a & b}")
print(f"Difference: {a - b}")
print(f"Symmetric: {a ^ b}")
```

```bash
voidpy e sets.py
voidpy r sets.void
```

### Example 22: Enumerate

```python
# enumerate.py
fruits = ["apple", "banana", "cherry"]
for index, fruit in enumerate(fruits):
    print(f"{index}: {fruit}")
```

```bash
voidpy e enumerate.py -l 3
voidpy r enumerate.void
```

### Example 23: Zip

```python
# zip.py
names = ["Alice", "Bob", "Charlie"]
ages = [25, 30, 35]
for name, age in zip(names, ages):
    print(f"{name} is {age} years old")
```

```bash
voidpy e zip.py
voidpy r zip.void
```

### Example 24: Map and Filter

```python
# mapfilter.py
numbers = [1, 2, 3, 4, 5]

doubled = list(map(lambda x: x * 2, numbers))
print(f"Doubled: {doubled}")

evens = list(filter(lambda x: x % 2 == 0, numbers))
print(f"Evens: {evens}")
```

```bash
voidpy e mapfilter.py -l 5
voidpy r mapfilter.void
```

### Example 25: Nested Data

```python
# nested_data.py
users = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 35}
]

for user in users:
    print(f"{user['name']}: {user['age']}")

total_age = sum(u["age"] for u in users)
print(f"Total age: {total_age}")
```

```bash
voidpy e nested_data.py -l 4
voidpy r nested_data.void
```

### Example 26: Global Variables

```python
# global.py
counter = 0

def increment():
    global counter
    counter += 1

increment()
increment()
increment()
print(f"Counter: {counter}")
```

```bash
voidpy e global.py
voidpy r global.void
```

### Example 27: Break and Continue

```python
# break_continue.py
for i in range(10):
    if i == 3:
        continue
    if i == 7:
        break
    print(i)
```

```bash
voidpy e break_continue.py -l 3
voidpy r break_continue.void
```

### Example 28: Password Generator

```python
# password.py
import random
import string

def generate_password(length=12):
    chars = string.ascii_letters + string.digits + "!@#$%"
    password = ''.join(random.choice(chars) for _ in range(length))
    return password

print(generate_password())
print(generate_password(16))
print(generate_password(8))
```

```bash
voidpy e password.py -l 7
voidpy r password.void
```

### Example 29: Simple Calculator

```python
# calculator.py
def calc(a, op, b):
    if op == '+':
        return a + b
    elif op == '-':
        return a - b
    elif op == '*':
        return a * b
    elif op == '/':
        return a / b if b != 0 else "Error"
    return "Unknown"

print(calc(10, '+', 5))
print(calc(10, '-', 5))
print(calc(10, '*', 5))
print(calc(10, '/', 5))
```

```bash
voidpy e calculator.py -l 5
voidpy r calculator.void
```

### Example 30: Number Guessing

```python
# guess.py
import random

secret = random.randint(1, 100)
attempts = 0

while True:
    guess = random.randint(1, 100)
    attempts += 1
    if guess == secret:
        print(f"Found {secret} in {attempts} attempts!")
        break
```

```bash
voidpy e guess.py -l 4
voidpy r guess.void
```

### Example 31: Fibonacci Sequence

```python
# fib.py
def fib_list(n):
    result = []
    a, b = 0, 1
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result

print(fib_list(10))
print(fib_list(15))
```

```bash
voidpy e fib.py -l 5
voidpy r fib.void
```

### Example 32: Prime Numbers

```python
# primes.py
def is_prime(n):
    if n < 2:
        return False
    for i in range(2, int(n**0.5) + 1):
        if n % i == 0:
            return False
    return True

primes = [n for n in range(100) if is_prime(n)]
print(f"Primes under 100: {primes}")
```

```bash
voidpy e primes.py -l 5
voidpy r primes.void
```

### Example 33: Sorting

```python
# sorting.py
numbers = [5, 2, 8, 1, 9, 3]
print(f"Original: {numbers}")
print(f"Sorted: {sorted(numbers)}")
print(f"Reversed: {sorted(numbers, reverse=True)}")

words = ["banana", "apple", "cherry"]
print(f"Alphabetical: {sorted(words)}")
```

```bash
voidpy e sorting.py
voidpy r sorting.void
```

### Example 34: Statistics

```python
# stats.py
data = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]

avg = sum(data) / len(data)
minimum = min(data)
maximum = max(data)
total = sum(data)

print(f"Data: {data}")
print(f"Average: {avg}")
print(f"Min: {minimum}")
print(f"Max: {maximum}")
print(f"Sum: {total}")
```

```bash
voidpy e stats.py -l 3
voidpy r stats.void
```

### Example 35: Multi-Layer Example

```python
# multi_layer.py
print("Testing multi-layer encryption")

def process(x):
    result = x * 2
    result = result + 10
    result = result ** 2
    return result

for i in range(5):
    print(f"process({i}) = {process(i)}")
```

```bash
# Encrypt with different layers
voidpy e multi_layer.py -l 1 -o layer1.void
voidpy e multi_layer.py -l 5 -o layer5.void
voidpy e multi_layer.py -l 10 -o layer10.void

# Run any of them
voidpy r layer5.void
```

---

## API Reference

### encrypt(source, output, layers)
Encrypt Python file to .void format.

| Parameter | Type | Description |
|-----------|------|-------------|
| source | str | Python file path |
| output | str | Output .void file path (optional) |
| layers | int | Encryption layers (default: 3) |

### enc(data)
Execute encrypted data directly.

| Parameter | Type | Description |
|-----------|------|-------------|
| data | bytes | Encrypted .void data |

### run(file)
Execute encrypted .void file.

| Parameter | Type | Description |
|-----------|------|-------------|
| file | str | Path to .void file |

### protect(source, output, layers)
Alias for encrypt with default 5 layers.

### execute(file)
Alias for run.

---

## Python API Examples

### Basic Usage

```python
import voidpy

# Encrypt a file
voidpy.encrypt("script.py", "script.void")

# Run encrypted file
voidpy.run("script.void")
```

### Custom Layers

```python
import voidpy

# 5 layers for stronger protection
voidpy.encrypt("important.py", "important.void", layers=5)

# 7 layers for critical code
voidpy.encrypt("secret.py", "secret.void", layers=7)
```

### Inline Encryption

```python
import voidpy

# Encrypt and get data
data = voidpy.encrypt_inline("print('Hello from void!')")

# Execute the data
voidpy.enc(data)
```

### VoidAPI Class

```python
from voidpy import VoidAPI

api = VoidAPI()
api.set_layers(5)

# Encrypt file
api.encrypt_file("app.py", "app.void")

# Encrypt code string
data = api.encrypt_code("print('Protected!')")

# Run file
api.run_file("app.void")

# Run encrypted data
api.run_data(data)

# All in one
api.encrypt_and_run("print('Quick test!')")
```

---

## VoidAPI Class Reference

| Method | Description |
|--------|-------------|
| `set_layers(n)` | Set encryption layers |
| `encrypt_file(src, out)` | Encrypt file |
| `encrypt_code(code)` | Encrypt code string |
| `run_file(file)` | Run .void file |
| `run_data(data)` | Run encrypted bytes |
| `encrypt_and_run(code)` | Encrypt and execute |

---

## File Structure

```
voidpy/
    __init__.py   - Main API
    cor.py        - Core Engine
    prs.py        - AST Parser
    stm.py        - State Manager
    crp.py        - Cryptography
    vm.py         - Virtual Machine
    api.py        - VoidAPI Class
    cli.py        - CLI Interface
```

---

## Encryption Strength

| Layers | Strength | Use Case |
|--------|----------|----------|
| 1 | Basic | Testing |
| 3 | Standard | Normal use (default) |
| 5 | Strong | Sensitive code |
| 7 | Very Strong | Critical applications |
| 10 | Maximum | Maximum security |

---

## Technical Specifications

| Feature | Specification |
|---------|---------------|
| Fake State Ratio | 75%+ |
| Encryption Rounds | 16 per layer |
| Key Derivation | SHA-256 based |
| Padding | Random, variable length |
| Header | 19 bytes with checksum |
| Compression | zlib level 9 |

---

## Error Codes

| Code | Meaning |
|------|---------|
| MERO_FUK_INVALID_MAGIC | Not a valid .void file |
| MERO_FUK_CORRUPTED | File is corrupted |
| MERO_NIL_VALUE | Null value encountered |
| MERO_EXECUTION_BLOCKED | Execution prevented |

---

## Supported Python Features

| Feature | Support |
|---------|---------|
| Variables | Full |
| Functions | Full |
| Classes | Partial |
| Loops (for/while) | Full |
| Conditionals (if/else) | Full |
| Lists | Full |
| Dictionaries | Full |
| Tuples | Full |
| Sets | Full |
| String operations | Full |
| Math operations | Full |
| Imports | Full |
| Lambda | Full |
| Comprehensions | Partial |
| Try/Except | Partial |
| With statements | Partial |

---

## Performance

| Operation | Speed |
|-----------|-------|
| Encryption | Fast |
| Execution | Near-native |
| Memory | Low overhead |

---

## Best Practices

1. Use 5+ layers for production code
2. Keep original .py files secure
3. Test encrypted code before deployment
4. Use different layer counts for different files
5. Use `voidpy check` to verify file integrity
6. Use batch mode for multiple files

---

## Adding Custom Obfuscation

You can extend voidpy with additional obfuscation layers by modifying the state manager (`stm.py`) and crypto module (`crp.py`).

### Adding Custom State Types

```python
# In stm.py - add new fake state types
def _gen_fake(self, idx):
    fake_types = [
        'MERO_TRAP',      # Trap state
        'MERO_DEAD',      # Dead end
        'MERO_NIL',       # Null operation
        'MERO_VOID',      # Void reference
        'MERO_FUK',       # Anti-analysis trap
        'QP4RM_DECOY',    # Decoy operation
        'MERO_LOOP',      # Infinite loop trap
        'MERO_JUNK',      # Junk data
    ]
    # Generate more complex fake states
    return {'id': f'F{idx:04d}', 'type': random.choice(fake_types)}
```

### Adding Custom Encryption Algorithms

```python
# In crp.py - add your own cipher
def _my_custom_cipher(self, data, seed):
    result = bytearray(data)
    
    # Your custom algorithm here
    for i in range(len(result)):
        # Custom transformation
        result[i] = (result[i] + seed + i * 7) & 0xFF
        result[i] = ((result[i] << 4) | (result[i] >> 4)) & 0xFF
    
    return bytes(result)

# Add to encrypt_layer function:
def encrypt_layer(self, data, seed):
    # ... existing code ...
    data = self._my_custom_cipher(data, rseed)  # Add here
    # ... rest of code ...
```

### Increasing Fake State Ratio

```python
# In stm.py - modify fake state ratio
def add_fake_states(self, states):
    real_count = len(states)
    # Change ratio: 90% fake states instead of 75%
    fake_count = int(real_count * 9)  # 9x fake = 90%
    # ... rest of function ...
```

### Adding More Encryption Rounds

```python
# In crp.py - increase rounds
class VoidCrypto:
    def __init__(self):
        self._rnd = 32  # Change from 16 to 32 rounds
        # ...
```

### Custom State Fragmentation

```python
# In stm.py - fragment into more pieces
def fragment_logic(self, states):
    result = []
    for state in states:
        if state.get('type') == 'DEF':
            # Split into 8 fragments instead of 4
            for i in range(8):
                frag = {'id': f"{state['id']}_F{i}", 'type': 'FRAG'}
                result.append(frag)
        result.append(state)
    return result
```

### Security Recommendations

For maximum protection:
1. Use 10 layers encryption
2. Increase fake states to 90%+
3. Add 32+ encryption rounds
4. Fragment operations into 8+ pieces
5. Add custom ciphers with unique algorithms

---

## License

MIT License

---

## Contact

Developer: **MERO**
Telegram: [@QP4RM](https://t.me/QP4RM)

Quick contact: `voidpy on`

---

## Version History

| Version | Changes |
|---------|---------|
| 1.0.0 | Initial release |

---

voidpy - Where Python Code Becomes Void