python‐core‐v1

python-core-v1 Branch Guide

The python-core-v1 branch is a modular refactored version of the initial prototype (python-core) with the addition of initial documentation, a Command-Line Interface (CLI), and Remote Procedure Call (RPC) support.

This branch is currently in the Development (Ongoing) stage.

---

Project Structure

Open-wChain/
├── app/ # Main application & interface
│ ├── api/ # HTTP API for blockchain nodes
│ │ ├── main.py # Entry point API server
│ │ └── routes/ # Routing endpoint API (modular)
│ ├── cli/ # Command-Line Interface (CLI) tools
│ │ ├── __init__.py
│ │ ├── node.py # CLI for managing blockchain nodes
│ │ ├── wallet_cli.py # CLI for wallets (create, send, view balance, etc.)
│ │ └── __pycache__/ # Python bytecode file
│ ├── config.py # Global application configuration
│ ├── __pycache__/ # Python cache for the `app` package
│ └── web/ # (Optional) Web UI for interaction
│
├── docs/ # Project documentation
│ └── INITIAL_DEVELOPMENT.md # Initial development guide (Q1 milestone)
│
├── lib/ # Core library (core blockchain)
│ ├── chain/ # Blockchain module
│ │ ├── blockchain.py # Chain & block validation implementation
│ │ ├── block.py # Block structure and logic
│ │ ├── tx_pool.py # Temporary transaction pool
│ │ └── __init__.py
│ ├── data.bak/ # Blockchain data backup (testing)
│ │ ├── blocks.json
│ │ ├── peers.json
│ │ ├── tx_pool.json
│ │ └── wallets.json
│ ├── node/ # Node module (network & communication)
│ │ ├── peers.py # Peer list management
│ │ ├── server.py # Server node & sync mechanism
│ │ └── __init__.py
│ └── wallet/ # Wallet module
│ ├── wallet.py # Wallet creation & management logic
│ └── __init__.py
│
├── LICENSE # Project license (WPCL v1.0)
├── README-en.md # Main documentation (English)
├── README.md # Main documentation (Indonesian)
├── requirements.txt # List of Python dependencies
├── scripts/ # Additional scripts (deployment / utils)
├── storage/ # Active blockchain data
│ └── data/
│ ├── blocks.json # Blockchain data
│ ├── peers.json # Peer list
│ ├── tx_pool.json # Active transaction pool
│ ├── wallets.json # Active wallets
│ └── README.md # Data format explanation
└── tests/ # Unit test & dummy data
└── chain/
└── fuckydummy.py # Dummy test (example/debug)

---

Installation

git clone -b python-core-v1 --single-branch https://github.com/WarceuProject/Open-wChain.git
cd Open-wChain
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

Technical Notes

• All modular code is located in lib/
• Separate CLI in app/cli
• Separate API in app/api
• JSON data is located in storage/data for easy backup and testing
• The new structure will be standardized for the python-core-v1 branch

---

Running Node Developer & Debugging

1. Run Node (Start)

Make sure you are in the project root (python-core-v1) and run:

python3 -m app.cli.node start

• start starts the developer node.

2. Stop Node

If the node module supports the stop command:

python3 -m app.cli.node stop

3. Monitor Logs / Debug

If node writes logs to a file, for example, debug.log:

tail -f storage/data/debug.log

• -f follows the log in real-time. Use Ctrl+C to stop.

Additional Tips

• Run node in the background:

python3 -m app.cli.node start &

or

nohup python3 -m app.cli.node start > storage/data/debug.log 2>&1 &

• Ensure all dependencies are installed:

pip install -r requirements.txt

---

Testing Node via cURL (HTTP Methods)

The OwCN node provides several endpoints for testing using curl.

1. Test Node Running

• Endpoint: /
• Method: GET

curl http://localhost:8000/

Expected output:

{"status": "running"}

2. Full Chain

• Endpoint: /fullchain
• Method: GET

curl http://localhost:8000/fullchain

3. RPC Endpoints

• Endpoint: /rpc
• Method: POST
• Content-Type: application/json

a. Get the number of blocks

curl -X POST http://localhost:8000/rpc\
-H "Content-Type: application/json" \
-d '{"method": "wcn_blockNumber", "params": []}'

b. Mine blocks

curl -X POST http://localhost:8000/rpc\
-H "Content-Type: application/json" \
-d '{"method": "wcn_mineBlock", "params": ["miner_address"]}'

c. Check balance

curl -X POST http://localhost:8000/rpc\
-H "Content-Type: application/json" \
-d '{"method": "wcn_getBalance", "params": ["wallet_address"]}'

d. Send transaction

curl -X POST http://localhost:8000/rpc\
-H "Content-Type: application/json" \
-d '{ 
"method": "wcn_sendTransaction", 
"params": [{ 
"from": "sender_address", 
"publicKey": "sender_public_key", 
"signature": "signed_data", 
"data": {"to": "receiver_address", "value": 10} 
}]
}'

4. Peer Management

a. Add peers

• Endpoint: /add_peer
• Method: POST

curl -X POST http://localhost:8000/add_peer\
-H "Content-Type: application/json" \
-d '{"url": "http://peer_ip:8000"}'

b. View peer list

• Endpoint: /peers
• Method: GET

curl http://localhost:8000/peers

5. Chain & Sync

a. Take the current chain

• Endpoint: /chain
• Method: GET

curl http://localhost:8000/chain

b. Sync blocks from peers

• Endpoint: /sync
• Method: POST

curl -X POST http://localhost:8000/sync \
-H "Content-Type: application/json" \
-d '{"index": 5, "hash": "block_hash", "transactions": []}'

Note

• Use Content-Type: application/json for all POST requests.
• Endpoints may be added or changed as the node evolves.
• Use jq for JSON parsing:

curl http://localhost:8000/fullchain | jq

---

Wallet CLI - Usage & Examples

Run the wallet CLI:

python3 -m app.cli.wallet_cli

The prompt will appear:

[openwchain-wallet] Type help or ? to list commands.
[wallet-cli/dev] >

1. Viewing Available Commands

help

Output:

Documented commands (type help <topic>):
=======================================
balance create exit help info list mine refresh select send

2. Creating a New Wallet

create mywallet

Output:

[✓] Wallet created and selected as default.
Alias: mywallet
Address: WCN123abc...

3. Viewing the Wallet List

list

Output:

* mywallet:WCN123abc...:0.00000000 WCN

4. Selecting the Default Wallet

select mywallet

Output:

[✓] Selected wallet: mywallet

5. Viewing Wallet Information

info mywallet

Output (formatted JSON):

{
"alias": "mywallet",
"address": "WCN123abc...",
"publicKey": "pubkey_here",
"privateKey": "privkey_here",
"balance": "0.00000000 WCN"
}

6. Check Wallet Balance

balance WCN123abc...

Output:

Balance: 0.00000000 WCN

7. Refresh All Wallet Balances

refresh

Output:

[✓] Wallets updated.

8. Send Transaction

send WCN456def... 1.25

Output if successful:

{'result': 'Transaction added to pool'}

If the balance is insufficient:

[!] Insufficient balance. You have 0.50000000 WCN, need 1,250,000,000 WCN.

9. Mining Block

mine

Output:

[⛏️] Mined block: 000abc123def...

10. Exit Wallet CLI

exit

Output:

Goodbye!

---

Note

• This branch is not final and may contain major changes to the code structure.
• It is recommended to use it only for development and experiment.