Introduction
Project Name:
Renterd Upgrade Guard (pre-upgrade config and MySQL migration preflight for renterd)
Name of the organization or individual submitting the proposal: Crackdevs
Crackdevs is a builder collective focused on developer tooling and core infrastructure, building and maintaining things like CLIs, SDKs, templates, IDE extensions, deployment workflows, and other glue code that makes blockchain development less painful.
Team member backgrounds (not limited to):
Victor Durosaro
a) Background: Web3 and backend engineer with strong Node.js and NestJS experience.
b) Work samples
i) nestjs-auction-system is a real-time auction backend built with NestJS, highlighting concurrency handling, WebSockets updates, caching, and background jobs. https://github.com/psyberpath/nestjs-auction-system
ii) nestjs-esp-integration-api is a NestJS REST API integrating Mailchimp and GetResponse, including API key validation, list retrieval, rate limiting, and PostgreSQL via TypeORM. https://github.com/psyberpath/nestjs-esp-integration-api
Ifedimeji Omoniyi
a) Background: Technical product manager with experience across developer tooling, protocols, and infrastructure.
Describe your project.
Renterd Upgrade Guard is a standalone CLI that operators run before upgrading renterd. It is designed to reduce two concrete upgrade failure classes that have already been reported publicly:
Config break startup failure: An apt upgrade from renterd v1.1.1 to v2.0.1 left the service unable to start due to YAML unmarshal errors caused by removed or renamed config fields.
MySQL migration failure: renterd migrations failed on MySQL due to trigger creation requirements under binary logging and privilege constraints, resulting in a fatal migration error at startup.
What the tool does
Config preflight (PASS or FAIL):
The CLI validates a real renterd.yml against the target renterd version’s config schema and fails when the target version would reject the config at startup due to unknown keys or type mismatches.
MySQL migration preflight (PASS, FAIL, or WARN):
If the deployment uses MySQL, the CLI performs read-only checks that are directly related to the migration failure class described in issue 910.
It returns FAIL only when a known risky state is confirmed from the checks it can perform.
It returns WARN when it cannot confirm risk from read-only checks but can point to explicit follow-up checks.
Outputs
A clear terminal summary with remediation steps.
A machine-readable JSON report.
Exit code 0 for PASS, 1 for FAIL. A WARN does not fail by default.
Scope is intentionally narrow
Version 1 supports renterd only.
Version 1 targets startup-blocking upgrade failures and migration preflight checks, not general runtime diagnosis.
How operators use it
Run a single command before restart, for example:
renterd-upgrade-guard check --to v2.0.1 --config /etc/renterd/renterd.yml
If PASS, proceed with the upgrade and restart.
If FAIL, fix the specific keys reported, rerun until PASS, then upgrade.
How does the projected outcome serve the Foundation’s mission of user-owned data?
The v2 transition increased the importance of reliable operations across the modular daemon stack. When operators upgrade and renterd fails to start due to config drift or migrations failing, it increases downtime risk and raises the operational cost of running Sia storage reliably.
This grant focuses on a practical reliability improvement: converting known “restart-and-break” outcomes into a fast, repeatable pre-upgrade check that operators can run before restarting renterd.
We cannot provide grants to residents of jurisdictions under increased FATF monitoring, those that have active OFAC sanctions, or those that fail our bank compliance tests. We also cannot provide grants if your payment bank account is located in those same locations. Please review the following list.
Are you a resident of any jurisdiction on that list? Yes/No
No
Will your payment bank account be located in any jurisdiction on that list? Yes/No
No
Grant Specifics
Amount of money requested and justification with a reasonable breakdown of expenses:
$10,000 USD total
160 hours at $62.50 per hour
Budget breakdown (exact total $10,000):
Config schema bundle generator for pinned renterd versions and version selection logic, 34 hours, $2,125
Config validator engine (unknown keys, type checks, remediation report, JSON output, exit codes), 42 hours, $2,625
MySQL migration preflight module (read-only checks tied to the failure class in issue 910), 20 hours, $1,250
GitHub Action wrapper and CI wiring, 22 hours, $1,375
Regression fixtures and tests seeded from real failure signatures, 12 hours, $750
Docs and operator workflows (systemd-safe wrapper, Docker flow, examples), 10 hours, $625
30-day maintenance window (bug fixes, edge cases, one patch release if needed), 20 hours, $1,250
Total: 160 hours, $10,000
The Foundation can only pay out grant funds in $USD via ACH or wire. Grant payments will be made monthly.
Acknowledged.
What is the high-level architecture overview for the grant? What security best practices are you following?
High-level architecture
CLI binary: renterd-upgrade-guard
Core command: check
Inputs
Path to renterd.yml
Target renterd version tag
Optional MySQL connection parameters for read-only introspection
Versioned schema bundles (how this works in practice)
The project includes a small build-time helper that can be compiled against a specific renterd tag and reflect on renterd’s config structs and YAML tags to emit a JSON schema bundle.
The released CLI ships with schema bundles for these pinned targets:
v1.1.1
v2.0.1
The renterd stable release tag current at project start, pinned in the repo during Week 1
The CLI selects the schema bundle for --to <tag> and validates the operator’s config.
Validation behavior
Unknown keys fail.
Type mismatches fail.
The tool does not claim to validate all runtime invariants. It focuses on configuration parse failures and migration preflight checks that can be assessed deterministically.
MySQL migration preflight (read-only, migration-focused)
-
Checks MySQL server variables that influence trigger creation under binary logging and related trust settings.
-
Attempts to inspect user grants where the server permits it.
-
Returns FAIL only when a risky state is confirmed. Otherwise returns WARN with explicit follow-up checks.
Outputs
Human remediation report with exact YAML paths and clear messages.
JSON report for automation.
Exit code 0 PASS, 1 FAIL.
Security best practices
-
No credentials are logged.
-
MySQL checks are read-only and do not alter schema or data.
-
Dependencies are pinned and minimal.
-
Release artifacts include checksums.
What are the goals of this small grant? Please provide a general timeline for completion.
Goals
Reduce renterd upgrade downtime risk by preflighting two known startup failure classes:
Config parse failures from removed or renamed YAML keys
MySQL migration hard failures tied to privileges and binary logging conditions
Timeline (5 weeks)
Week 1
Repo setup and CLI skeleton
Define JSON report format
Implement schema bundle generator and produce bundles for v1.1.1 and v2.0.1
Week 2
Strict YAML parsing
Unknown key detection and type checks
Human remediation report with exact YAML paths
Add fixtures that reproduce the invalid keys from issue 1852 and assert FAIL
Week 3
Add schema bundle for the renterd stable release tag current at project start and pin it
Implement GitHub Action wrapper and artifact upload
Release packaging pipeline for Linux, macOS, Windows
Week 4
Implement MySQL migration preflight module
Add tests and fixtures derived from the failure class in issue 910
Ensure FAIL only occurs when risk is confirmed by read-only checks
Week 5
Polish UX and docs
Ship systemd-safe and Docker-safe wrapper examples
Cut v1.0.0 release and publish checksummed binaries
Publish example PASS and FAIL outputs for the supported versions
Acceptance criteria (binary pass/fail)
-
A config containing the removed fields shown in issue 1852 produces FAIL and lists each invalid key.
-
A valid config for the selected target schema produces PASS.
-
Confirmed MySQL conditions consistent with the migration failure class in issue 910 produce FAIL with a specific remediation message. Otherwise the tool returns WARN with explicit follow-up checks.
-
The tool runs without starting
renterd.
What are your plans for this project following the grant?
Provide 30 - 40 days of maintenance for bug fixes and edge cases reported by operators, included in the budget.
Any expansion to other daemons is out of scope for this $10,000 grant.
Potential risks that will affect the outcome of the project:
Risk: Some renterd constraints are enforced at runtime, not during YAML parsing.
Mitigation: The tool is scoped to startup-blocking parse failures and migration preflight checks that can be assessed deterministically.
Risk: Some operators expect packaging to protect them automatically during upgrades.
Mitigation: Provide copy-paste wrappers for systemd pre-restart checks and Docker entrypoint checks so operators can adopt the preflight step without requiring packaging changes.
Risk: MySQL environments differ, and some privilege state may be partially opaque to read-only checks.
Mitigation: The tool fails only when it can confirm risk from read-only checks. Otherwise it warns and provides explicit follow-up checks, grounded in the failure class in issue 910.
Development Information
Will all of your project’s code be open-source?
Yes. MIT license.
Do you agree to submit monthly progress reports?
Yes. Progress reports will be posted monthly in the forum thread.
Contact info
Email:
[[email protected]]
Any other preferred contact methods:
X/Twitter: @crackdevs