UNLOCK-5: Stamps Feature, Shopify Purchase Completed Integration

[sebpalluel]

Stamps Feature - Shopify Purchase Completed Integration

Background

The Stamps feature allows for the creation of ERC-1155 stampNftContracts for each new campaign created on the Shopify back-office. A campaign can consist of one or several gate IDs, which are defined on the Shopify side. The stampNftContract will hold metadata containing the associated Shopify gate IDs.

Objectives

1. Create stampNft records for each product (and its variants, if applicable) when a campaign is defined from the Shopify back-office.
2. Upon receiving the checkouts/paid webhook signal from Shopify, assign the relevant quantity of stampNft to the buyer's wallet address.
3. Create or update the corresponding stampNftSupply records in the database to reflect the ownership and quantity of the assigned stampNft.

Specifications

Campaign Creation

• When a new campaign is created on the Shopify back-office, create a new stampNftContract record with the following metadata:

  {
    "shopify_gates_id": ["gate1_id", "gate2_id", ...]
  }

• For each product (and its variants, if applicable) associated with the campaign, create a corresponding stampNft record with the following metadata:

  {
    "shopify_product_id": "product_id",
    "shopify_product_variant_id": "variant_id",
  }

  • shopify_product_variant_id can be null if the product has no variants.

Webhook Integration

• Subscribe to the checkouts/paid webhook from Shopify to receive notifications when a purchase is completed.
• Upon receiving the webhook payload, parse the line_items to determine the relevant stampNft and the quantity purchased for each item.
• For each line_item:
  • Retrieve the corresponding stampNft record based on the shopify_product_id and shopify_product_variant_id (if applicable).
  • Mint the appropriate quantity of the stampNft to the buyer's wallet address.
    • The buyer's wallet address can be resolved through either a metafield or by resolving the address with the customer ID in the shopifyCustomer model.
  • Create or update the stampNftSupply record in the database with the following information:
    • tokenId: The token ID of the stampNft.
    • contractAddress: The address of the stampNftContract.
    • chainId: The chain ID of the blockchain network.
    • currentOwnerAddress: The buyer's wallet address.
    • lastNftTransferId: The ID of the nftTransfer record associated with this minting event.
    • amount: The quantity of the stampNft assigned to the buyer.
    • status: Set to 'CONFIRMED' upon successful minting.

Additional Considerations

• Error Handling:
  • If an error occurs during the minting process, set the error field in the stampNftSupply record to the error message and the status to 'FAILED'.
  • Implement appropriate error logging and monitoring to track and resolve any issues.
• Security:
  • Ensure that the webhook endpoint is properly authenticated and validated to prevent unauthorized access.
  • Implement necessary security measures to protect sensitive data, such as customer information and wallet addresses.
• Performance:
  • Optimize the webhook handling process to minimize latency and ensure timely minting of stampNft to buyers' wallets.
  • Consider implementing asynchronous processing or background jobs for resource-intensive tasks to maintain responsiveness.

Testing

• Develop comprehensive unit tests to verify the functionality of the campaign creation, webhook handling, and database interactions.
• Perform integration tests to ensure the seamless integration between the Shopify back-office, webhook notifications, and the minting process.
• Conduct thorough testing with various scenarios, including different product types, variants, and edge cases, to ensure robustness and reliability.

Documentation

• Provide clear and concise documentation for setting up and configuring the Stamps feature, including the necessary Shopify back-office configurations and webhook setup.
• Document the API endpoints, request/response formats, and any specific requirements or constraints.
• Include troubleshooting guides and common error scenarios to assist with issue resolution.