Add Structured Error Metadata for Validation Failures

[Lakes41]

Difficulty: Hard

Type: Refactor

Summary

Improve validation errors so consumers can identify which input field failed and why without parsing human-readable error strings.

Current Behaviour

Input validation throws GuildPassError, but consumers may need to inspect error messages to determine whether the invalid value was a wallet address, guild ID, resource ID, role ID, chain ID, or configuration field.

Expected Behaviour

Validation errors should include structured metadata such as field, reason, and optionally a safe value or valueType. This allows applications to show precise form errors and log useful diagnostics without brittle string parsing.

Suggested Implementation

Update validation helpers to throw GuildPassError with structured metadata. Add a common validation error helper to keep error shape consistent. Ensure sensitive values are not included directly unless they are safe identifiers such as guild IDs or public wallet addresses. Update tests to assert metadata for common invalid inputs.

Files or Areas Likely Affected

• src/utils/validation.ts
• src/utils/address.ts
• src/config/sdkConfig.ts
• src/contracts/contractClient.ts
• src/errors/GuildPassError.ts
• src/errors/errorCodes.ts
• tests/

Acceptance Criteria

• Invalid wallet address errors include a structured field value.
• Invalid guild ID errors include a structured field value.
• Invalid resource ID errors include a structured field value.
• Invalid role ID errors include a structured field value.
• Invalid config errors include the affected config field.
• Error metadata avoids exposing secrets such as apiKey.
• Tests cover structured metadata for input and config validation failures.

Additional Notes

Keep existing error messages readable for humans, but make machine-readable metadata the preferred integration surface.

[whitezaddy]

Hello maintainer. I have the experience and skills to resolve this issue. ETA 2hrs

[clintjeff2]

Hello, I have 6 years of experience working on tasks like this and handling similar challenges across backend, frontend, and smart-contract development. I have carefully read and fully understood the task requirements, and I am confident I can deliver a clean, efficient, and well-tested solution promptly. I always ensure high-quality implementation, maintainability, and adherence to best practices.

ETA 2 hours

[grantfox-oss]

🦊 GrantFox — @whitezaddy has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #129)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.