[Fatimasanusi]

Summary

This pull request implements on-chain puzzle completion verification, solution hash comparison, SAC token reward payouts, and CAP-54 style puzzle reward NFT minting.

Closes #683
Closes #680
Closes #671
Closes #670

---

Key Changes

1. Puzzle Solution Hash Verification (#683)

• On-chain (stellar_hunts):
  • Added add_question_with_hash to store questions directly with precomputed 32-byte SHA-256 hashes.
  • Updated submit_answer to support direct 32-byte solution hash validation alongside raw answers.
  • Added verify_solution_hash view and Error::HashMismatch rejection.
• Frontend (usePuzzleContract.js):
  • Implemented computeSolutionHash using Web Crypto (crypto.subtle) for consistent client-side SHA-256 generation.
  • Updated submitAnswer to hash solutions before on-chain submission.

2. Cross-Contract Reward Token Payouts (#680)

• On-chain (stellar_hunts):
  • Added admin configuration: set_reward_token, get_reward_token, set_default_reward_amount, and set_puzzle_reward_amount.
  • Implemented try_payout_reward utilizing the SAC / token interface (soroban_sdk::token::Client).
  • Added failure handling using try_transfer, raising Error::RewardTransferFailed if token transfer fails.
  • Added claim_puzzle_reward entrypoint for claiming completed puzzle rewards.

3. NFT Minting Contract for Puzzle Rewards (#671)

• On-chain (stellar_hunts_nft):
  • Added mint_puzzle_reward_nft restricted to authorized hunter contracts via minter.require_auth() and has_minter_role.
  • Stored PuzzleRewardMetadata containing puzzle name, difficulty, completion timestamp, and minter address.
  • Prevented duplicate mints for completed puzzles via Error::DuplicateCompletion.
  • Added has_puzzle_reward and get_puzzle_metadata view methods.
• Hunter Contract (stellar_hunts):
  • Added claim_puzzle_nft for cross-contract NFT minting upon puzzle completion.

4. Puzzle Completion Entrypoint (#670)

• On-chain (stellar_hunts):
  • Implemented complete_puzzle(env, caller, puzzle_id, solution_hash) entrypoint to validate solutions trustlessly on-chain.
  • Emits puzzle_completed event with (caller, puzzle_id).
  • Records completion in persistent storage (DataKey::CompletedPuzzle) and prevents duplicate completions (Error::AlreadyCompleted).
  • Automatically triggers token reward payouts when configured.
  • Added is_puzzle_completed view function.
• Frontend (usePuzzleContract.js):
  • Added completePuzzle hook action for executing completions with client-side hashing.

[drips-wave]

@Fatimasanusi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[dzekojohn4]

On-chain completion with solution hash verification — nicely done, the flow reads clearly. Ship it 🚀