feat: NFT Puzzle Access Rental Smart Contract

[Akinbola247]

Summary

Implements the contracts/puzzle_rental contract, allowing NFT owners to list exclusive puzzle access for rent in exchange for tokens, with time-bound access control, extension support, early termination with refunds, and a marketplace discovery index.

closes #81

What's Included

Contract (src/lib.rs)

Test (src/test.rs), 57 test passed, 0 failure

Data model

• RentalListing — owner-defined rental terms: price per period, duration, max periods, payment token, extension policy, and refund percentage
• RentalAgreement — active rental with time bounds, escrow tracking, and status
• RentalRecord — immutable history entry written on every terminal state (expired or terminated)

Core functions

Function	Description
initialize	Bootstrap admin and counters
create_listing	NFT owner publishes rental terms
cancel_listing	Owner removes listing; removed from marketplace index
rent	Renter pays for N periods; funds escrowed in contract
extend_rental	Renter pays for additional periods while active
expire_rental	Permissionless — anyone triggers expiry after end_time; releases escrow to owner
terminate_rental	Renter exits early; contract splits escrow between owner (earned) and renter (refund)
has_access	Time-bound access gate checked against current ledger timestamp
get_active_listings	Paginated marketplace discovery
get_owner_listings	Index query by owner
get_renter_rentals	Index query by renter
get_rental_history	Fetch archived record post-close

Acceptance Criteria

• NFTs listed for rental | ✅ create_listing
• Renters pay tokens for access | ✅ escrowed on rent
• Access expires automatically | ✅ has_access checks timestamp; expire_rental settles escrow
• Extensions work correctly | ✅ extend_rental with max period guard
• History tracked | ✅ RentalRecord written on every terminal state
• Contract deployed to testnet | ✅ https://stellar.expert/explorer/testnet/contract/CCGI5CWLTSQAUZRWTGTI5IV3K2DWCE6INYDZBG6KT5ELKHPQ6FZ7FNE3

---

Notes for Reviewers

• The marketplace index (ActiveListings) is stored in instance storage for efficient pagination. Cancelled listings are eagerly removed from the index.
• auto_expire_if_needed is called defensively inside extend_rental and terminate_rental to prevent acting on a rental that has silently lapsed — this avoids a class of race conditions around the boundary of end_time.

[Mkalbani]

@Akinbola247 Please resolve conflict

[Akinbola247]

@Mkalbani , the conflict has been resolved