Release Notes - August 2024

General

• Improvements to the OpenAPI Documentation continue to be made and this release has focused on documentation accuracy on the Standard Wallet API protocol, ThrillConnect and ThrillPots Gateway. This is an ongoing effort.

New Features

ThrillPots

• Recurring Raffles

  • In previous releases, raffles were limited to being once-off scheduled jackpots. In this release, we have extended the scheduling capabilities of the system to allow granular control of jackpot and raffle schedules.
  • Recurring Raffles require a schedule to be defined when the raffle is instantiated. To enable this, the POST /templates/instantiate API has been enhanced to accept a schedule as part of the payload.
  • Raffles can now be configured to run for durations of time defined in:
    • Seconds
    • Minutes
    • Hours
    • Days
    • Weeks
  • EXAMPLE: Instantiate a recurring raffle jackpot is scheduled for the full month of January 2025 that is only available from 12:00:00CET to 23:59:59CET each day:
    • POST http://thrillpots-service/templates/instantiate
    • Payload (Json)

    {
    	"template_owner_id": "thrilltech",
    	"template_id":  "recurring-raffle",
    	"instance_owner_id": "thrilltech",
    	"instance_name": "recurring-raffle",
    	"linked_instance": "ca93978e-6997-4e7a-a438-376783864849",
    	"schedule": {
    		// Wednesday, 1 January 2025 00:00:00
    		"timestamp_start": 1735689600000,
    		// Friday, 31 January 2025 23:59:59
    		"timestamp_end": 1738367999000,
    		"recurrence_rules": [
    			{
    				"frequency": {
    					"Daily": {
    						"hours": [
    							[
    								// 12:00:00 CET -> 23:59:59 CET
    								{"hour": 10, "minute": 0, "sec": 0},
    								{"hour": 21, "minute": 59, "sec": 59}
    							]
    						]
    					}
    				},
    				"interval": 1
    			}
    		]
    	}
    }
    

    • More information about scheduling can be found here

• Raffle Ticket Enhancements

  • As of this release, raffle tickets can be configured based on a player's base_wager or contribution. Previous releases only supported ticket costs based on contribution.
  • It is now possible to retrieve all of a player's raffle tickets for all active raffles (instead of retrieving them one raffle instance at a time).
    • ThrillPots Service:
      • GET /instances/raffle/tickets/brand/:brand_id/:player_id
    • ThrillPots Gateway:
      • GET /jackpots/instances/raffle/tickets/brand/:brand_id/:player_id

• Advanced Scheduling

  • As mentioned in the Recurring Raffles feature above, we have introduced a more advanced scheduling subsystem to the platform.
  • In ThrillPots, schedules are bound to a Jackpot Instance and a brand
  • Schedules are stored in a new MongoDB collection: thrillpots.instance_schedules
  • New APIs have been made available on ThrillPots Service to manage Instance Schedules:
    • GET /config/schedule - Retrieves schedules
      • Optional Query Parameters:
        • instance_id - filter the results by a specific instance
        • brand_id - filter the results by a specific brand
    • POST /config/schedule - Create a new schedule
      • This will create a new schedule for a specific Jackpot Instance and operator:brand.
      • If a schedule for this instance and brand already exists, this call will fail.
      • The body of the call has the following structure:

      {
      	"instance_id": String,
      	"brand_id": String,
      	"schedule": {
      		"timestamp_start": Integer, // unix timestamp
      		"timestamp_end": Integer, // optional unix timestamp
      		"recurrence_rules": [RecurrenceRuleItem] // 0..n element of recurrence rules
      	}
      }
      

      • More information about Schedule definitions can be found here
    • PUT /config/schedule - Update an existing schedule
      • The body of the payload is similar to the one user for the POST call:

      {
      	"instance_id": String,
      	"brand_id": String,
      	"schedule": { // optional
      		"timestamp_start": Integer, // unix timestamp
      		"timestamp_end": Integer, // optional unix timestamp
      		"recurrence_rules": [RecurrenceRuleItem] // 0..n element of recurrence rules
      	},
      	"enabled": Boolean // optional
      }
      

      • schedule and enabled are optional values. You only need to specify the field you wish to change.
      • To disable a schedule, set enabled to false.
        • NOTE: Be careful when disabling schedules for recurring raffles as it will cause the raffle to end during its next resolution period.

• Seed Boosts

  • The seed boosts feature allows operators to add additional funds to a Jackpot which will act as additional seed buffers when a jackpot is won.
  • Seed Boosts can be applied to specific pots within a Jackpot. For example, if you wished to add a Seed Boost to your top tier only, you could do so.
  • In order to use Seed Boosts, you simply need to add "surplus seed" to the pot of your choosing by calling a new POST /instances/adjustsurplus endpoint.
  • Example:
    • POST http://localhost:8084/instances/adjustsurplus
    • Header: Authorization
    • Value: Bearer AUTH_TOKEN_FOR_ADMIN@THRILLTECH.IO
    • Body:

    {
    	"instance_id": "5afac8be-fdf9-40dd-adf5-1b590a265b9f",
    	"pot_id": "mega",
    	"adjustment": {
    		"AdjustBy": 5000
    	},
    	"reason": "Adding €5000 seed boost to the mega pot"
    }
    

Changes/Improvements

ThrillPots

• Rejected Contribution Log Changes (to summaries) - DATA MIGRATION

  • PLEASE NOTE: This is an important change and will require system admins to be aware that the initial startup of the new ThrillPots Service could take a number minutes to succesfully complete the migration process.
  • The thrillpots.log_rejected_contributions collection is one of the busiest (and largest) collections in the system, but its use cases are limited.
  • In this release we have changed the structure of the storage for rejected contributions and moved to a summarised document per player.
  • Possible actions to be taken as part of the deployment:
    • If you do not use the log_rejected_contributions collection for any data analysis at the moment, you can choose to delete/drop the collection prior to launching the new services. This will reduce the time needed to perform the migration to mere seconds
    • If you do wish to retain the data in log_rejected_contributions and have it reflected in the new summaries, please make sure that your Container Management System does not restart the pod while the migration is running. This can either be done by increasing the number of allowed health check failures to provide up to 5-10 minutes for the migration, or increasing the period between health checks.
    • In general, we recommend allocating approximately 60s of time per 10m documents in the collection. Therefore, if you have a collection of 50m documents, we would recommend allocating at least 5-6 minutes for the migration to execute.

• Async Contribution Errors now carry metadata

  • For integrations that make use of asynchronous contributions, you may have noticed that the metadata supplied on the contribution call was not propogated on errors reported to the webhook.
  • This issue has now been addressed and the webhook will receive the original metadata on all errors under the metadata field.

• JackpotEventUpdate event changes

  • Added the following new fields to the event:
    • jackpot_type - Indicates where the instance is a Jackpot or a Raffle (these are the two valid values for this field)
    • timestamp_start - If the instance has a schedule, this field will contain the UTC timestamp for the starting time of the active jackpot instance
    • timestamp_end - If the instance has a schedule and an end time for the instance, this field will contain the UTC timestamp for the end
  • An example of the new structure looks like this:

  {
  	"event_type": "JackpotUpdateEvent",
  	"data": {
  		"id": "ab775921-0743-47d4-8ad2-cd60aae27b39",
  		"jackpot_type": "Raffle",
  		"currency": "EUR",
  		"pots": [
  			{
  				"id": "main",
  				"is_progressive": false,
  				"current_value": 100.0
  			}
  		],
  		"allowed_brands": [
  			"thrilltech:brand1",
  			"thrilltech:brand2",
  			"thrilltech:my-new-brand"
  		],
  		"allowed_sources": [
  			"raffle-test"
  		],
  		"status": "Active",
  		"timestamp_start": 1728604800000,
  		"timestamp_end": 1728691199000,
  		"last_updated": 1728604800000
  	}
  }
  

  • Resolve Raffles not actively updating to Active state based on scheduling

• Deprecated JP_REDIS_EVENT_CHANNEL and GW_REDIS_EVENT_CHANNEL environment variables

  • Previously, these environment variables contained the event channel that ThrillPots would send its events on internally (default was jackpot_events). This has now been deprecated.
  • ThrillPots now defaults to using an aligned channel name with the rest of the event channels in the system called thrillpots.events.

• Sources can now be queried by their ID

  • The GET /config/sources endpoint has been extended to accept a source_id query parameter
  • If supplied, this will filter the results by the provided source_id.

• Zero value contributions are allowed

  • Up until now, Jackpot Templates did not allow contribution values to be specified as ZERO.
  • As of this release, this restriction as been lifted (with certain caveats - explained below)
  • Reasons to allow zero-value contributions:
    • Promotional Jackpots: Promotional jackpots should allow zero value contributions if they are non-progressive and/or do not have value based tipping points
  • Caveats:
    • Zero value contributions can only be made to jackpots that are fully operator funded AND have all their pots defined as probability or time based tipping points.
    • For zero value contributions, there is no RTP to be calculated for wins

• WinEvent changes

  • In previous versions, the WinEvent was only broadcast to players of the brand on which the win occurred. In this release, the WinEvent is also broadcast to all brands that are participating in the jackpot.

• Improved Handling for Limited Jackpot Tiers

  • We have improved the handling of limited jackpot tiers. Limited Jackpot Tiers are tiers that are configured to only drop a certain amount of times. With this release, if the last available tier of a jackpot is a limited tier and the drop limit has been reached, the jackpot itself will automatically end (status == Ended) and the frontend will stop receiving JackpotUpdateEvents for the jackpot.

ThrillGate

• New Index on thrillgate.players:

  • Added a new compound index on thrillgate.players: ["operator_id", "brand_id", "provider_id", "source_id"]

• Standard Wallet Protocol

  • TransactionBatch contains the transactions property.
    • This is a list of the individual player transactions within the batch. The content of the TransactionBatch.transactions[].transaction_id field has been changed to contain a UUID in place of a concatenated string made up of transaction and player attribute data.
  • A Version 5 UUID has been used allowing for idempotent creation of this unique identifier. Version 5 UUID's consist of a namespace UUID and a name string. Together, they are unique within the system.
    • namespace: TransactionBatch.transaction_batch_id
    • name: TransactionBatch.transactions[].player_id

ThrillConnect

• Updated payload for Get Instance By Source endpoint
  • Affected endpoint:
    • GET /v1/thrillpots/instances/source/:source_id/brand/:brand_id
  • The response now contains three additional fields:
    • status - The status of the instance
    • timestamp_start - The UTC timestamp containing when the jackpot starts/started
    • timestamp_end - The UTC timestamp containing when the jackpot will end
  • These additions allow frontends to:
    • determine whether a jackpot is active for contributions
      • if status == Active, the jackpot is active within the schedule
      • if status == Pending, the jackpot is scheduled to start at a future time
    • determine if a raffle is currently active or not
      • if status == Active, the raffle is active and accepting contributions
      • if status == Pending, the raffle is scheduled to start at a future time (timestamp_start).

Thrill-ID

• Added improve Administration APIs for managing Organisational Units

  • Enable/Disable organisation:
    • PUT /admin/organisations/{org_id}/enable/{enable_flag}
    • No payload required
  • Add Organisational Units to an Organisation
    • PUT /admin/organisations/{org_id}/units
    • Payload:

    [
    	"Org unit A",
    	"Org unit B",
    	"Org unit C"
    ]
    

  • Remove Organisational Units from an Organisation
    • DELETE /admin/organisations/{org_id}/units
    • Payload:

    [
    	"Org unit A",
    	"Org unit B",
    	"Org unit C"
    ]
    

• Added DEBUG level logging for API requests

Bug Fixes

ThrillPots

• Missing template during Jackpot re-instantiation
  • If the source Jackpot Template which was used for instantiating a jackpot instance was missing when a Jackpot Instance had a win and needed to re-instantiate, the pot that was won would not actually reset correctly.
  • This situation can only occur through manual tampering in the ThrillPots database, but since it is a possibility, the issue needed to be resolved.
  • In a situation like this, the win itself will not be processed and error will be logged.
• Resolve Raffles not actively updating to Active state based on scheduling
• It is possible to retrieve all raffle tickets for all active Raffles for a specific player by omitting the instance_id on the PlayerRaffleTicketsRequest. For an example, please see here

Final Images