feat(soroban): implement royalty recipient update, deployment verific…

[Mosas2000]

Summary

This PR addresses and resolves Soroban NFT smart contract enhancements and API integrations across issues #672, #686, #684, and #683.

Related Issues

• Closes [Soroban] Update Royalty Recipient #672: Allow creators/recipients to update royalty recipient address
• Closes [Soroban] Deployment Verification Script #686: Add deployment verification script and status endpoint
• Closes [Soroban] Gas Usage Monitoring #684: Implement gas usage monitoring and metrics endpoint
• Closes [Soroban] Limited Metadata Update #683: Enforce one-time metadata update limit for NFT owners

---

Key Changes

1. Update Royalty Recipient (#672)

• Soroban Contract: Added update_royalty_recipient(env, token_id, new_recipient) restricting execution to current recipient authorization (current_recipient.require_auth()) and emitting RoyaltyRecipientUpdated.
• API & Swagger: Added PATCH /nfts/:id/royalty-recipient endpoint with request/response DTOs (UpdateRoyaltyRecipientDto, UpdateRoyaltyRecipientResponseDto) and full OpenAPI documentation.
• Royalty Distribution: Updated transfer_with_royalty and pay_royalty to direct future royalties to the updated recipient address.

2. Deployment Verification Script (#686)

• Soroban Contract: Added collection metadata view methods name() ("ClipCash NFT") and symbol() ("CLIP").
• Verification Tooling: Added automated verification script scripts/verify-deployment.ts and executable scripts/verify-deployment.sh that queries name(), symbol(), and default royalty configuration to produce a structured verification report.
• API & Swagger: Added GET /nfts/deployment-status endpoint returning post-deploy verification status.

3. Gas Usage Monitoring (#684)

• Metrics Service: Implemented GasMetricsService (src/nft/gas-metrics.service.ts) to track, benchmark, and log CPU instructions, memory bytes, and gas units consumed in key operations (mint, transfer).
• API & Swagger: Added GET /nfts/gas-stats endpoint returning average gas metrics and benchmark history examples (GasStatsResponseDto).

4. Limited Metadata Update (#683)

• Soroban Contract: Added update_metadata(env, token_id, new_metadata) requiring token owner authorization (token_data.owner.require_auth()), enforcing a strict single-update limit (Error::MetadataAlreadyUpdated), and emitting MetadataUpdated.
• API & Swagger: Added PATCH /nfts/:id/metadata endpoint with error response payload (MetadataUpdateLimitErrorDto) returning HTTP 400 Bad Request if a second update is attempted.

---

Verification & Testing

Automated Test Suites

• Soroban Contract Unit Tests: Executed cargo test in contracts/nft-contract — 66 passed, 0 failed.
• NestJS Unit Tests: Executed npm test -- src/nft/nft-enhancements.spec.ts — 6 passed, 6 total.
• Deployment Verification Script: Executed npx ts-node scripts/verify-deployment.ts — output verified: Status: SUCCESS (ALL CHECKS PASSED).

Verification Commands Executed

# 1. Smart contract unit tests
cd contracts/nft-contract && cargo test

# 2. NestJS unit tests
npm test -- src/nft/nft-enhancements.spec.ts

# 3. Post-deploy verification script
npx ts-node scripts/verify-deployment.ts

[drips-wave]

@Mosas2000 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