Skip to content

Commit 81f2124

Browse files
EtienneWalletEtienneWallet
authored
Merge pull request #178 from Catenscia/develop
Develop
2 parents 88e7fc7 + 5252502 commit 81f2124

File tree

87 files changed

+3920
-248
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+3920
-248
lines changed

‎.claude/settings.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(git status:*)",
5+
"Bash(git diff:*)",
6+
"Bash(git log:*)",
7+
"Bash(git add:*)",
8+
"Bash(git commit:*)",
9+
"Bash(git push:*)",
10+
"Bash(uv sync:*)",
11+
"Bash(uv run:*)",
12+
"Bash(bash scripts/local_checks.sh:*)",
13+
"Bash(bash scripts/launch_unit_tests.sh:*)",
14+
"Bash(bash scripts/launch_integration_tests.sh:*)",
15+
"Bash(bash scripts/check_python_code.sh:*)",
16+
"Bash(bash integration_tests/scripts/setup.sh:*)",
17+
"Bash(coverage run:*)",
18+
"Bash(bandit:*)",
19+
"Bash(flake8:*)",
20+
"Bash(ruff:*)",
21+
"Bash(pylint:*)",
22+
"Bash(python -m pytest:*)",
23+
"Bash(python -m mxops:*)"
24+
]
25+
}
26+
}

‎.claude/skills/check-code.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
description: Run all MxOps code quality checks required before PR
3+
user-invocable: true
4+
---
5+
6+
# Check Code
7+
8+
Run all MxOps code quality checks required before PR.
9+
10+
## Tools
11+
12+
1. **Bandit** - Security analysis (must have no issues)
13+
2. **Flake8** - Style checking (must pass, max-line-length=88)
14+
3. **Ruff** - Format + lint (must pass)
15+
4. **Pylint** - Code analysis (score >= 9.5)
16+
17+
## Usage
18+
19+
- `/check-code` - Run all checks
20+
- `/check-code --fix` - Auto-fix formatting issues first, then run checks
21+
22+
## Commands
23+
24+
Run all checks:
25+
```bash
26+
bash scripts/check_python_code.sh
27+
```
28+
29+
Auto-fix and check:
30+
```bash
31+
uv run ruff format mxops && uv run ruff check mxops --fix
32+
bash scripts/check_python_code.sh
33+
```
34+
35+
Or run individual tools:
36+
```bash
37+
# Security check
38+
uv run bandit -r mxops
39+
40+
# Style check
41+
uv run flake8 mxops tests integration_tests examples
42+
43+
# Format and lint
44+
uv run ruff format mxops
45+
uv run ruff check mxops
46+
47+
# Code analysis
48+
uv run pylint mxops
49+
```
50+
51+
## Notes
52+
53+
- All checks must pass before submitting a PR
54+
- Ruff can auto-fix many issues with `ruff format` and `ruff check --fix`
55+
- Pylint score must be >= 9.5

‎.claude/skills/integration-test.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
description: Run MxOps integration tests on chain-simulator
3+
user-invocable: true
4+
---
5+
6+
# Integration Test
7+
8+
Run MxOps integration tests on the MultiversX chain-simulator.
9+
10+
## Usage
11+
12+
- `/integration-test` - Run full integration test suite
13+
14+
## Steps
15+
16+
1. Start the chain-simulator
17+
2. Run setup script
18+
3. Execute integration tests
19+
4. Stop the chain-simulator
20+
21+
## Commands
22+
23+
```bash
24+
# Start chain-simulator (Docker must be running)
25+
uv run mxops chain-simulator start
26+
27+
# Run setup
28+
bash integration_tests/scripts/setup.sh chain-simulator
29+
30+
# Run tests
31+
bash scripts/launch_integration_tests.sh chain-simulator
32+
33+
# Stop chain-simulator
34+
uv run mxops chain-simulator stop
35+
```
36+
37+
## Requirements
38+
39+
- **Docker** must be running
40+
- Use `uv run mxops` for development version (not globally installed mxops)
41+
42+
## Notes
43+
44+
- The chain-simulator runs in Docker
45+
- Setup script deploys necessary contracts and configures test environment
46+
- Tests run against the local chain-simulator instance
47+
- Always stop the simulator after testing to free resources

‎.claude/skills/run-tests.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: Run MxOps unit tests with pytest and coverage
3+
user-invocable: true
4+
---
5+
6+
# Run Tests
7+
8+
Run MxOps unit tests with pytest and coverage.
9+
10+
## Usage
11+
12+
- `/run-tests` - Run all unit tests
13+
- `/run-tests tests/test_smart_values.py` - Run specific test file
14+
- `/run-tests -k "test_name"` - Run tests matching pattern
15+
16+
## Commands
17+
18+
For all tests:
19+
```bash
20+
bash scripts/launch_unit_tests.sh
21+
```
22+
23+
For specific tests or patterns:
24+
```bash
25+
uv run coverage run -m pytest tests/<path> --color=yes -vv
26+
```
27+
28+
## Notes
29+
30+
- Tests use pytest with coverage reporting
31+
- Coverage report is generated after test run
32+
- Use `uv run` prefix if running outside the virtual environment

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,8 @@ dmypy.json
139139
# Pyre type checker
140140
.pyre/
141141

142+
# git worktrees
143+
worktrees
142144

143145
# Exceptions
144-
!**/**/.gitkeep
146+
!**/**/.gitkeep

‎CLAUDE.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# MxOps Development Guide
2+
3+
MxOps is a Python automation tool for MultiversX blockchain. Users write YAML scene files that describe steps (contract deployments, calls, queries, token management) which MxOps executes.
4+
5+
## Quick Reference
6+
7+
### Essential Commands
8+
```bash
9+
# Install dev dependencies
10+
uv sync --group dev
11+
12+
# Run ALL checks before PR (required)
13+
bash scripts/local_checks.sh
14+
15+
# Run unit tests only
16+
bash scripts/launch_unit_tests.sh
17+
18+
# Run integration tests (chain-simulator)
19+
uv run mxops chain-simulator start
20+
bash integration_tests/scripts/setup.sh chain-simulator
21+
bash scripts/launch_integration_tests.sh chain-simulator
22+
uv run mxops chain-simulator stop
23+
```
24+
25+
### Testing Development Changes
26+
```bash
27+
# Use development version (NOT globally installed mxops)
28+
uv run mxops <command>
29+
# or
30+
python -m mxops <command>
31+
```
32+
33+
### Code Quality (all must pass for PR)
34+
- **Bandit**: `uv run bandit -r mxops` - no security issues
35+
- **Flake8**: `uv run flake8 mxops tests integration_tests examples` - max-line-length=88
36+
- **Ruff**: `uv run ruff format mxops && uv run ruff check mxops` - format + lint
37+
- **Pylint**: `uv run pylint mxops` - score >= 9.5
38+
39+
## Architecture
40+
41+
### Core Flow
42+
```text
43+
YAML Scene -> Steps -> Transactions/Queries -> MultiversX Network
44+
```
45+
46+
### Key Directories
47+
| Directory | Purpose |
48+
|-----------|---------|
49+
| `mxops/execution/steps/` | All step implementations (28 types) |
50+
| `mxops/smart_values/` | Dynamic value resolution (`%`, `$`, `&`, `=` syntax) |
51+
| `mxops/data/` | ScenarioData persistence per network+scenario |
52+
| `mxops/cli/` | CLI commands (execute, data, config, chain-simulator) |
53+
| `tests/` | Unit tests (pytest) |
54+
| `integration_tests/` | Chain-simulator/devnet integration tests |
55+
56+
### All Step Types (28)
57+
**Contracts**: `ContractDeploy`, `ContractUpgrade`, `ContractCall`, `ContractQuery`, `FileFuzzer`
58+
**Transfers**: `Transfer`
59+
**Tokens**: `FungibleIssue`, `NonFungibleIssue`, `SemiFungibleIssue`, `MetaIssue`, `FungibleMint`, `NonFungibleMint`, `ManageFungibleTokenRoles`, `ManageNonFungibleTokenRoles`, `ManageSemiFungibleTokenRoles`, `ManageMetaTokenRoles`
60+
**Setup**: `GenerateWallets`, `ChainSimulatorFaucet`, `R3D4Faucet`, `AccountClone`
61+
**Control**: `Loop`, `Scene`, `SetVars`, `SetSeed`, `Assert`, `Wait`, `Log`, `Python`
62+
63+
### Smart Values Syntax
64+
| Symbol | Source | Example |
65+
|--------|--------|---------|
66+
| `%` | Scenario data | `%contract_id.address`, `%saved_value` |
67+
| `$` | Environment var | `$MY_ENV_VAR` |
68+
| `&` | Config file | `&PROXY` |
69+
| `=` | Formula | `=10**18`, `=randint(1,5)` |
70+
71+
**Formula functions**: `int`, `str`, `float`, `rand`, `randint`, `choice`, `ceil`, `len`
72+
73+
**Composition**: `%{${OWNER}_token.identifier}`, `={%{amount_1} + %{amount_2}}`
74+
75+
## Adding New Steps
76+
77+
1. Create dataclass in `mxops/execution/steps/<module>.py`
78+
2. Inherit from `Step` (non-tx) or `TransactionStep` (tx)
79+
3. Implement `_execute()` or `build_unsigned_transaction()`
80+
4. Export in `mxops/execution/steps/__init__.py`
81+
5. Add tests in `tests/`
82+
83+
Pattern:
84+
```python
85+
@dataclass(kw_only=True)
86+
class MyStep(TransactionStep):
87+
my_param: SmartStr
88+
optional_param: SmartInt | None = None
89+
90+
def build_unsigned_transaction(self) -> Transaction:
91+
param = self.my_param.get_evaluated_value()
92+
...
93+
```
94+
95+
## Branch/Commit Conventions
96+
97+
- **Branches**: `feature/<name>`, `fix/<name>`, `refactor/<name>`, `docs/<name>`, `test/<name>`, `breaking/<name>`
98+
- **Commits**: Conventional Commits format (automated versioning depends on this)
99+
- **PRs target**: `develop` branch
100+
101+
## Gotchas
102+
103+
1. **Smart values must be quoted in YAML**: Use `"%var"` not `%var`
104+
2. **Step type suffix optional**: `ContractCall` and `ContractCallStep` both work
105+
3. **Formula results are typed**: `=10**18` returns int, use `=str(...)` if string needed
106+
4. **Scenario isolation**: Each network+scenario combo has separate persisted data
107+
5. **ABI recommended**: Always provide ABI for automatic argument encoding/decoding

‎README.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,6 @@ MxOps is used below to fetch information from the [live Onedex contract](https:/
6060
- 9 # id of the pair to get the details of
6161
```
6262
63-
```{dropdown} Query results
64-
:class-title: normal-title
65-
:color: light
66-
6763
```json
6864
[
6965
{

‎docs/dictionary/custom_wordlist.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ AppDir
44
AppFolder
55
arg
66
backend
7+
backoff
78
bitwise
89
blake
910
blockchain
@@ -36,6 +37,7 @@ monotypes
3637
Monotypes
3738
natively
3839
os
40+
permissioned
3941
pipx
4042
png
4143
pre

‎docs/dictionary/multiversx_wordlist.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ init
2929
JEX
3030
jex
3131
Jexchange
32+
keystores
3233
LedgerAccount
3334
localnet
3435
mainnet

‎docs/dictionary/project_wordlist.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ devnet
1717
EnumWithEverything
1818
EsdtMinter
1919
ExecuteTrade
20+
FailCheck
2021
FileFuzzerStep
2122
françois
2223
Freepik
@@ -30,7 +31,9 @@ github
3031
jacques
3132
jean
3233
Keystore
34+
keystore
3335
Knop
36+
LogCheck
3437
mainnet
3538
Maiar
3639
msc

0 commit comments

Comments
 (0)