Skip to content

Commit 778d811

Browse files
J0ET0MJ0ET0M
committed
added documentation
1 parent cc5da05 commit 778d811

File tree

4 files changed

+225
-6
lines changed

4 files changed

+225
-6
lines changed

‎tools/Qubic.ContractGen/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Qubic.ContractGen
2+
3+
A code generator that parses C++ smart contract headers from `qubic-core` and produces C# bindings for use with `Qubic.Core`.
4+
5+
## What It Does
6+
7+
Reads the C++ header files in `deps/qubic-core/src/contracts/` and generates one `.g.cs` file per contract into `src/Qubic.Core/Contracts/Generated/`. Each generated file contains:
8+
9+
- A static contract class (e.g. `QxContract`, `QswapContract`)
10+
- Strongly-typed C# structs for every `_input` and `_output` pair
11+
- Correct field offsets matching MSVC `/Zp8` struct alignment
12+
- `Serialize()` / `Deserialize()` methods on each struct for binary round-tripping
13+
- Function and procedure metadata (ID, name, input/output types)
14+
15+
## Supported Contracts
16+
17+
| Index | Name | Header |
18+
|-------|------|--------|
19+
| 1 | Qx | Qx.h |
20+
| 2 | Quottery | Quottery.h |
21+
| 3 | Random | Random.h |
22+
| 4 | Qutil | QUtil.h |
23+
| 5 | Mlm | MyLastMatch.h |
24+
| 6 | Gqmprop | GeneralQuorumProposal.h |
25+
| 7 | Swatch | SupplyWatcher.h |
26+
| 8 | Ccf | ComputorControlledFund.h |
27+
| 9 | Qearn | Qearn.h |
28+
| 10 | Qvault | QVAULT.h |
29+
| 11 | Msvault | MsVault.h |
30+
| 12 | Qbay | Qbay.h |
31+
| 13 | Qswap | Qswap.h |
32+
| 14 | Nost | Nostromo.h |
33+
| 15 | Qdraw | Qdraw.h |
34+
| 16 | Rl | RandomLottery.h |
35+
| 17 | Qbond | QBond.h |
36+
| 18 | Qip | QIP.h |
37+
| 19 | Qraffle | QRaffle.h |
38+
| 20 | Qrwa | qRWA.h |
39+
| 21 | Qrp | QReservePool.h |
40+
| 22 | Qtf | QThirtyFour.h |
41+
| 23 | Qduel | QDuel.h |
42+
43+
## Usage
44+
45+
```bash
46+
# Run from the repo root (auto-detects paths)
47+
dotnet run --project tools/Qubic.ContractGen
48+
49+
# Or pass the repo root explicitly
50+
dotnet run --project tools/Qubic.ContractGen -- /path/to/Qubic.Net
51+
```
52+
53+
Output:
54+
55+
```
56+
Headers: /path/to/Qubic.Net/deps/qubic-core/src/contracts
57+
Output: /path/to/Qubic.Net/src/Qubic.Core/Contracts/Generated
58+
59+
[01] Qx OK (5 functions, 7 procedures)
60+
[02] Quottery OK (5 functions, 4 procedures)
61+
...
62+
63+
Generated 22 files, skipped 1.
64+
```
65+
66+
## Prerequisites
67+
68+
- .NET 8.0 SDK
69+
- The `qubic-core` git submodule must be initialized:
70+
```bash
71+
git submodule update --init
72+
```
73+
74+
## Architecture
75+
76+
```
77+
Qubic.ContractGen/
78+
Program.cs # Entry point, contract registry, orchestration
79+
Parsing/
80+
CppHeaderParser.cs # C++ header lexer/parser
81+
ContractModel.cs # Intermediate representation (functions, structs, fields)
82+
TypeMapper.cs # C++ → C# type mapping with alignment info
83+
Generation/
84+
CSharpEmitter.cs # IR → C# code emitter with MSVC /Zp8 layout
85+
```
86+
87+
### Parsing Pipeline
88+
89+
1. **CppHeaderParser** reads the `.h` file and extracts the contract's main struct (e.g. `struct QX : public ContractBase`)
90+
2. Finds all `_input` / `_output` struct pairs and matches them to functions (read-only) or procedures (state-changing)
91+
3. Resolves typedefs (including contract-internal ones like `typedef Array<Order, 256> OrdersArray`)
92+
4. Handles nested structs, `Array<T,N>` templates, and `id` (32-byte public key) types
93+
94+
### Code Generation
95+
96+
- **CSharpEmitter** walks the parsed model and produces idiomatic C# with:
97+
- `[StructLayout]` attributes where useful
98+
- Manual field offset computation matching MSVC `/Zp8` rules (min of field alignment, 8)
99+
- `BinaryPrimitives` for little-endian serialization
100+
- Proper handling of `byte[]` arrays, nested struct arrays, and padding bytes

‎tools/Qubic.ScTester/Program.cs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
builder.Services.AddSingleton<ContractDiscovery>();
99
builder.Services.AddScoped<ScQueryService>();
1010

11-
builder.WebHost.UseUrls("http://localhost:5050");
11+
builder.WebHost.UseUrls("http://127.0.0.1:0");
1212

1313
var app = builder.Build();
1414
app.UseStaticFiles();
@@ -17,16 +17,16 @@
1717

1818
app.Lifetime.ApplicationStarted.Register(() =>
1919
{
20-
var url = "http://localhost:5050";
21-
Console.WriteLine($"Qubic SC Tester running at {url}");
20+
var address = app.Urls.FirstOrDefault() ?? "http://localhost:5050";
21+
Console.WriteLine($"Qubic SC Tester running at {address}");
2222
try
2323
{
2424
if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
25-
Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
25+
Process.Start(new ProcessStartInfo(address) { UseShellExecute = true });
2626
else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
27-
Process.Start("open", url);
27+
Process.Start("open", address);
2828
else
29-
Process.Start("xdg-open", url);
29+
Process.Start("xdg-open", address);
3030
}
3131
catch { /* Browser auto-open is best-effort */ }
3232
});

‎tools/Qubic.ScTester/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Qubic.ScTester
2+
3+
A Blazor Server web application for browsing and testing Qubic smart contract functions interactively.
4+
5+
## Features
6+
7+
- **Auto-discovery** of all generated contract bindings via reflection
8+
- **Three query backends**: RPC, Bob (JSON-RPC), and Direct Network (TCP)
9+
- **Dynamic form generation** for function inputs based on struct metadata
10+
- **Smart input handling**:
11+
- 60-character Qubic identity strings are auto-converted to 32-byte public keys for `byte[]` fields
12+
- Asset name fields (`ulong`) accept text like `QX`, `CFB`, `QUTIL` and encode them automatically
13+
- **Per-field "Show Text" toggle** for `byte[]` output values (hex vs ASCII)
14+
- **Tabular display** for `Array<T,N>` output fields with sortable columns
15+
- **Connection test** button on the home page (calls `Qutil.GetFees` as a smoke test)
16+
17+
## Usage
18+
19+
```bash
20+
dotnet run --project tools/Qubic.ScTester
21+
```
22+
23+
The app picks a random available port and opens your browser automatically. The URL is printed to the console.
24+
25+
## Query Backends
26+
27+
| Backend | Protocol | Default Endpoint | Description |
28+
|---------|----------|-----------------|-------------|
29+
| **RPC** | HTTP/JSON | `https://rpc.qubic.org` | Official Qubic RPC API (base64-encoded payloads) |
30+
| **Bob** | JSON-RPC 2.0 | `https://bob.qubic.li` | QubicBob node with async nonce-based polling (hex-encoded payloads) |
31+
| **Direct Network** | TCP | `corenet.qubic.li:21841` | Raw Qubic P2P protocol (binary `RequestContractFunction` type 42) |
32+
33+
Switch backends from the navbar dropdown or the home page radio buttons. The URL / host:port is editable inline.
34+
35+
## Prerequisites
36+
37+
- .NET 8.0 SDK
38+
- Generated contract bindings (run `Qubic.ContractGen` first if the `Contracts/Generated/` folder is empty)
39+
40+
## Publishing
41+
42+
Build self-contained binaries for distribution:
43+
44+
```bash
45+
# Windows
46+
dotnet publish tools/Qubic.ScTester -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -p:EnableCompressionInSingleFile=true -o publish/win-x64
47+
48+
# Linux
49+
dotnet publish tools/Qubic.ScTester -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true -p:EnableCompressionInSingleFile=true -o publish/linux-x64
50+
51+
# macOS (Apple Silicon)
52+
dotnet publish tools/Qubic.ScTester -c Release -r osx-arm64 --self-contained -p:PublishSingleFile=true -p:EnableCompressionInSingleFile=true -o publish/osx-arm64
53+
54+
# macOS (Intel)
55+
dotnet publish tools/Qubic.ScTester -c Release -r osx-x64 --self-contained -p:PublishSingleFile=true -p:EnableCompressionInSingleFile=true -o publish/osx-x64
56+
```
57+
58+
### Running the Published Binary
59+
60+
**Windows:** Double-click `Qubic.ScTester.exe` or run it from a terminal.
61+
62+
**Linux:**
63+
```bash
64+
chmod +x Qubic.ScTester
65+
./Qubic.ScTester
66+
```
67+
68+
**macOS:** If cross-compiled from another OS, you need to codesign and remove quarantine before running:
69+
```bash
70+
chmod +x Qubic.ScTester
71+
codesign --force --deep -s - Qubic.ScTester
72+
xattr -d com.apple.quarantine Qubic.ScTester
73+
./Qubic.ScTester
74+
```
75+
76+
## Project Structure
77+
78+
```
79+
Qubic.ScTester/
80+
Program.cs # Host setup, DI registration
81+
ScQueryService.cs # Backend abstraction (RPC / Bob / TCP)
82+
ContractDiscovery.cs # Reflection-based contract discovery
83+
Components/
84+
App.razor # Root component
85+
Layout/
86+
MainLayout.razor # Navbar with backend selector
87+
NavMenu.razor # Sidebar contract list
88+
Pages/
89+
Home.razor # Dashboard with connection settings
90+
ContractPage.razor # Contract detail: forms, queries, results
91+
SmokeTest.razor # Quick connectivity check
92+
```
93+
94+
## Dependencies
95+
96+
- `Qubic.Core` - Contract models and identity handling
97+
- `Qubic.Rpc` - HTTP RPC client
98+
- `Qubic.Bob` - JSON-RPC client
99+
- `Qubic.Crypto` - Cryptographic primitives
100+
- `Qubic.Network` - Direct TCP node client

‎tools/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Tools
2+
3+
Developer tools for working with Qubic smart contracts.
4+
5+
| Tool | Description |
6+
|------|-------------|
7+
| [Qubic.ContractGen](Qubic.ContractGen/) | Parses C++ smart contract headers from `qubic-core` and generates C# bindings with correct struct layouts, type mappings, and alignment. |
8+
| [Qubic.ScTester](Qubic.ScTester/) | Blazor Server web UI for browsing and testing all generated smart contract functions against live Qubic nodes via RPC, Bob, or direct TCP. |
9+
10+
## Quick Start
11+
12+
```bash
13+
# 1. Generate C# contract bindings from the C++ headers
14+
dotnet run --project Qubic.ContractGen
15+
16+
# 2. Launch the SC Tester web UI
17+
dotnet run --project Qubic.ScTester
18+
# Open http://localhost:5050
19+
```

0 commit comments

Comments
 (0)