SC-W8-18: Reference Hook Contract and Trait Interface

[Cedarich]

Labels: Soroban, Stellar Wave, contract, hook, dx
Complexity: Medium (150)

Description
Hook registration, an allowlist, and failure isolation exist, but there is no published interface or example implementation, so an external integrator has to read hook.rs and guess the expected signature and semantics.

Acceptance Criteria

• A documented trait or interface defines what a hook contract must implement.
• A minimal reference hook contract is committed and builds in the workspace.
• Integration tests register the reference hook and exercise success and failure paths.
• Documentation covers hook invocation ordering, failure isolation behaviour, and resource limits.

[onlyonee1]

@onlyonee1 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

hi maintainer i will like to work on this issue please

ℹ️ Repo Maintainers: To accept this application, review their application or assign @onlyonee1 to this issue.

[VerifiedFlemzy1]

@VerifiedFlemzy1 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainer, I'd like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @VerifiedFlemzy1 to this issue.

[drips-wave]

Congratulations, @VerifiedFlemzy1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @VerifiedFlemzy1: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[YngPrince11]

@YngPrince11 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I would like to work on this issue.. please assign me...

ℹ️ Repo Maintainers: To accept this application, review their application or assign @YngPrince11 to this issue.

[ibochivincent-lang]

@ibochivincent-lang has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’d like to work on Issue #879 because the existing hook registration, allowlist, and failure-isolation mechanisms are not backed by a published interface or reference implementation. This makes the integration experience unnecessarily difficult for external developers who have to inspect hook.rs and infer the expected contract behavior.

I will first review the current hook implementation, registration flow, allowlist checks, invocation logic, failure handling, and workspace contract structure to identify the exact interface an external hook contract must satisfy.

I will then define and document a clear trait or interface describing the required hook contract methods, argument and return types, authorization expectations, and failure semantics. The interface will be designed around the behavior already supported by the existing hook system rather than introducing an incompatible abstraction.

I will create a minimal reference hook contract and add it to the workspace so contributors can use it as a concrete example. The reference implementation will remain intentionally small while demonstrating the correct integration pattern and building successfully with the rest of the Soroban contracts.

I will then add integration coverage that registers the reference hook and exercises both a successful invocation and a controlled failure. The failure path will verify that the existing failure-isolation behavior works as documented and that a failing hook cannot incorrectly break the surrounding operation.

The documentation will explain the full lifecycle of a hook, including registration, allowlist requirements, invocation ordering relative to the main operation, failure isolation, and the resource limits a hook must operate within.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ibochivincent-lang to this issue.

[attyolu]

@attyolu has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Please Maintainer. Few hours left and i just have 150 points. Pls assign this issue to me. I'm begging

ℹ️ Repo Maintainers: To accept this application, review their application or assign @attyolu to this issue.