Programmatic Subscription

How you manage the subscription depends on your randomness needs. You can configure your subscriptions using the Subscription Manager, but these examples demonstrate how to create your subscription and add your consumer contracts programmatically. For these examples, the contract owns and manages the subscription. Any wallet can provide funding to those subscriptions.

You can view and monitor your subscriptions in the Subscription Manager even if you create them programmatically. Go to vrf.chain.link to open the Subscription Manager.

Modifying subscriptions and configurations

Subscription configurations do not have to be static. You can change your subscription configuration dynamically by calling the following functions using the VRFCoordinatorV2Interface:

• Change the list of approved subscription consumers with:
  • addConsumer(uint64 subId, address consumer).
  • removeConsumer(uint64 subId, address consumer).
• Transfer the subscription ownership with:
  • requestSubscriptionOwnerTransfer(uint64 subId, address newOwner).
  • acceptSubscriptionOwnerTransfer(uint64 subId).
• View the subscription with getSubscription(uint64 subId).
• Cancel the subscription with cancelSubscription(uint64 subId).

To send LINK to the subscription balance, use the LINK token interface with LINKTOKEN.transferAndCall(address(COORDINATOR), amount, abi.encode(subId)). Any wallet can fund a subscription.

See the example in the Subscription manager contract section to learn how to create a contract that can change your subscription configuration.

Subscription manager contract

In this example, the contract operates as a subscription owner and can run functions to add consuming contracts to the subscription. The consuming contracts must include the requestRandomWords() function with the correct coordinator parameters and the correct subscription ID to request random values and use the subscription balance. The consuming contracts must also include the fulfillRandomWords() function to receive the random values.

Subscription owners and consumers do not have to be separate. This contract not only allows adding consumers with addConsumer(address consumerAddress) but can also act as a consumer by running its own requestRandomWords() function. This example contract includes a createNewSubscription() function in the constructor() that creates the subscription and adds itself as a consumer automatically when you deploy it.

To use this contract, compile and deploy it in Remix.

1. Open the contract in Remix.

2. Compile and deploy the contract using the Injected Provider environment. The contract includes all of the configuration variables that you need, but you can edit them if necessary. For a full list of available configuration variables, see the Supported Networks page.

   This contract automatically creates a new subscription when you deploy it. Read the s_subscriptionId variable to find your subscription ID. You can use this value to find the subscription at vrf.chain.link.

3. In this example, the topUpSubscription() function sends LINK from your contract to the subscription. Fund your contract with at least three testnet LINK. Alternatively, you can send LINK directly to the subscription at vrf.chain.link. Any address can provide funding to a subscription balance. If you need testnet LINK, you can get it from faucets.chain.link.

4. Run the topUpSubscription() function to send LINK from your contract to your subscription balance. For this example, specify a value of 3000000000000000000, which is equivalent to three LINK.

5. Run the requestRandomWords() function. The request might take several minutes to process. Track the pending request status at vrf.chain.link.

6. You can also add and test consumer contracts using the same programmatic subscription process:

   1. Create and deploy a consumer contract that includes the following components:

      • The requestRandomWords() function and the required variables and your subscription ID.
      • The fulfillRandomWords() callback function.

      You can use the example from the Get a Random Number guide.

   2. After you deploy the consumer contract, add it to the subscription as an approved consumer using the addConsumer() function on your subscription manager contract. Specify the address of your consumer contract.

   3. On the consumer contract, run the requestRandomWords() function to request and receive random values. The request might take several minutes to process. Track the pending request status at vrf.chain.link.

      The consumer contract can continue to make requests until your subscription balance runs out. The subscription manager contract must maintain sufficient balance in the subscription so that the consumers can continue to operate.

   4. If you need to remove consumer contracts from the subscription, use the removeConsumer() function. Specify the address of the consumer contract to be removed.

7. When you are done with your contracts and the subscription, run the cancelSubscription() function to close the subscription and send the remaining LINK to your wallet address. Specify the address of the receiving wallet.

Funding and requesting simultaneously

You can fund a subscription and request randomness in a single transaction. You must estimate how much the transaction might cost and determine the amount of funding to send to the subscription yourself. See the Subscription billing page to learn how to estimate request costs.