Managing Subscriptions

This guide explains how to manage Chainlink Functions subscriptions. Currently, the best way to create and manage subscriptions is by using the Chainlink Functions Starter Kit commands.

Before you begin

Complete the setup steps in the Getting Started guide: The Getting Started Guide shows you how to set up your environment with the necessary tools for creating and managing subscriptions and completing the tutorials.

Subscriptions

You can find Subscription Management commands, descriptions, and parameters in the Chainlink Functions Starter Kit reference documentation.

Create a subscription

Run the functions-sub-create task to create a new subscription account:

npx hardhat functions-sub-create --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-create --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Creating Functions billing subscription
Waiting 2 blocks for transaction 0x018a04da4d1a3e8c14ceb8fbca786a897566a37c0b4cb9a9a36ca35a43806a3b to be confirmed...
Subscription created with ID: 27

Created subscription with ID: 27
Owner: 0x9d087fC03ae39b088326b67fA3C788236645b717
Balance: 0.0 LINK
0 authorized consumer contracts:
[]

Create and fund a subscription

Run the functions-sub-create task with the amount parameter to create a new subscription account and fund it. The amount is in LINK.

Optionally, you can also add your consumer contract by including the --contract flag with the address of your consumer contract. You can always add more consumer contracts later.

npx hardhat functions-sub-create --amount REPLACE_LINK_AMOUNT --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-create --amount 0.5 --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Creating Functions billing subscription
Waiting 1 blocks for transaction 0xc5990756f7728da53d8fdce3c715ef47b29094ad2a895435c1d871e2d2c5f725 to be confirmed...
Subscription created with ID: 28
Duplicate definition of Transfer (Transfer(address,address,uint256,bytes), Transfer(address,address,uint256))
Funding with 0.5 LINK
Waiting 2 blocks for transaction 0x822a0d667d8b4ba0849e486b65a7a7d495cb322528d15254dbc7a7a01b7e1458 to be confirmed...
Subscription 28 funded with 0.5 LINK

Created subscription with ID: 28
Owner: 0x9d087fC03ae39b088326b67fA3C788236645b717
Balance: 0.5 LINK
0 authorized consumer contracts:
[]

Get Subscription details

Run the functions-sub-info task with the subid (subscription ID) parameter to fetch the following items:

• Subscription balance
• Subscription owner
• A list of authorized client contract addresses

npx hardhat functions-sub-info --subid REPLACE_SUBSCRIPTION_ID --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-info --subid 28 --network polygonMumbai
secp256k1 unavailable, reverting to browser version

Subscription 28 owner: 0x9d087fC03ae39b088326b67fA3C788236645b717
Balance: 0.5 LINK
0 authorized consumer contracts:
[

Fund a Subscription

Run the functions-sub-fund task with subid (subscription ID) and amount parameters. Note that amount is in LINK.

npx hardhat functions-sub-fund --subid REPLACE_SUBSCRIPTION_ID --amount REPLACE_LINK_AMOUNT --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-fund --subid 28 --amount 0.1  --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Funding subscription 28 with 0.1 LINK
Duplicate definition of Transfer (Transfer(address,address,uint256,bytes), Transfer(address,address,uint256))
Waiting 2 blocks for transaction 0x2940a9c8d5cbe521f68552f53c329de0261b179baeb40cafe1b7a1dc3d3bde24 to be confirmed...

Subscription 28 has a total balance of 0.6 LINK

Add a consumer contract to a Subscription

Prerequisites

You must deploy a Chainlink Functions consumer contract before you can add it to your subscription. You can skip on-chain contract verification with the --verify false flag.

If you do need to verify your contract on-chain, sign up for a free API key for your network scanner and include it in your .env.enc file:

1. Sign up for an API key:

   • Polygon Mumbai: Sign up for a free Polygonscan API key.
   • Sepolia: Sign up for a free Etherscan API key.

2. Include it in your .env.enc by running npx env-enc set and set POLYGONSCAN_API_KEY or ETHERSCAN_API_KEY depending on your network.

Deploy a consumer contract:

npx hardhat functions-deploy-client --verify false --network REPLACE_NETWORK

Example:

$ npx hardhat functions-deploy-client --verify true --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Deploying FunctionsConsumer contract to mumbai

__Compiling Contracts__
Nothing to compile

Waiting 2 blocks for transaction 0x91b6f29e7ab2ba372b980f2193dc00f8614ba33e2554b98bec59246720d4f1dd to be confirmed...

Verifying contract...
Nothing to compile
Successfully submitted source code for contract
contracts/FunctionsConsumer.sol:FunctionsConsumer at 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C
for verification on the block explorer. Waiting for verification result...

Successfully verified contract FunctionsConsumer on Etherscan.
https://mumbai.polygonscan.com/address/0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C#code
Contract verified

FunctionsConsumer contract deployed to 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C on mumbai

Note the deployed consumer contract address, which is 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C in this example output. You will need your consumer contract address later when you make requests.

Command

Run the functions-sub-add task with the subid (subscription ID) and contract parameters to add a contract to a subid.

npx hardhat functions-sub-add --subid REPLACE_SUBSCRIPTION_ID --contract REPLACE_CONSUMER_CONTRACT_ADDRESS --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-add --subid 28 --contract 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Adding consumer contract address 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C to subscription 28
Waiting 2 blocks for transaction 0x743f1b2c0345b4d4ab415f921b719b5e7c62bfcf4425b43404eb059f137628b7 to be confirmed...

Added consumer contract address 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C to subscription 28
1 authorized consumer contract for subscription 28:
[ '0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C' ]

Remove a consumer contract from a Subscription

Prerequisites

Your subscription must have at least one authorized consumer contract. See the Add a consumer contract to a Subscription section.

Command

Run the functions-sub-remove task with the subid (subscription ID) and contract parameters to remove a contract from a subid.

npx hardhat functions-sub-remove --subid REPLACE_SUBSCRIPTION_ID --contract REPLACE_CONSUMER_CONTRACT_ADDRESS --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-remove --subid 28 --contract 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Removing consumer contract address 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C to subscription 28
Waiting 2 blocks for transaction 0x01c1c0f70c87aa84112e5b47e99eea733a8dabd925e82c943d627723d4490697 to be confirmed...

Removed consumer contract address 0x191D570c489e73e4869aE4D62ab8a0ab71Ce2B5C from subscription 28
0 authorized consumer contracts for subscription 28:
[]

Transfer ownership of a Subscription

1. Run the functions-sub-transfer task with the subid (subscription ID) and newowner (new owner's address) parameters to transfer the subid to the newowner.

   npx hardhat functions-sub-transfer --subid REPLACE_SUBSCRIPTION_ID --newowner REPLACE_NEW_OWNER_ADDRESS --network REPLACE_NETWORK

   Example:

   $ npx hardhat functions-sub-transfer --subid 28 --newowner 0x109690437eC588caA0caA414D1bb447aA423d018 --network polygonMumbai
   secp256k1 unavailable, reverting to browser version
   
   Transferring the subscription to a new owner will require generating a new signature for encrypted secrets.
   Any previous encrypted secrets will no longer work with this subscription ID and must be regenerated by the new owner.
   Do you still want to continue? (y) Yes / (n) No
   y
   Requesting ownership transfer of subscription 28 to new owner 0x109690437eC588caA0caA414D1bb447aA423d018
   Waiting 2 blocks for transaction 0x2748692191f89b5a40d4063feff6a14a7d79e796e5a689f58efd71c572dd4936 to be confirmed...
   
   Ownership transfer to 0x109690437eC588caA0caA414D1bb447aA423d018 requested for subscription 28.  The new owner must now accept the transfer request.

2. The new owner must run the functions-sub-accept task with the subid (subscription ID) parameter.

   npx hardhat functions-sub-accept --subid REPLACE_SUBSCRIPTION_ID --network REPLACE_NETWORK

   If you are the new owner, set the PRIVATE_KEY in the .env.enc file to the new owner's account private key by running npx env-enc set.

   $ npx hardhat functions-sub-accept --subid 28 --network polygonMumbai
   secp256k1 unavailable, reverting to browser version
   Accepting ownership of subscription 28
   Waiting 2 blocks for transaction 0x5de5155ac0635ed03c0fb707d490b847ec161136455bae3a565d931bb9355821 to be confirmed...
   Ownership of subscription 28 transferred to 0x109690437eC588caA0caA414D1bb447aA423d018
   
   Subscription 28 owner: 0x109690437eC588caA0caA414D1bb447aA423d018
   Balance: 0.6 LINK
   0 authorized consumer contracts:
   []

Cancel a Subscription

Run the functions-sub-cancel task with the subid (subscription ID) and refundaddress parameters. The refundaddress parameter determines which wallet address the remaining funds are set to.

npx hardhat functions-sub-cancel --subid REPLACE_SUBSCRIPTION_ID --refundaddress REPLACE_RECEIVER_ADDRESS --network REPLACE_NETWORK

Example:

$ npx hardhat functions-sub-cancel --subid 28 --refundaddress 0x9d087fC03ae39b088326b67fA3C788236645b717 --network polygonMumbai
secp256k1 unavailable, reverting to browser version
Canceling subscription 28
Waiting 2 blocks for transaction 0x12ef85523b6c8e7773ed577cac057ce60c8e4c5c66c80c0e341612db5815c549 to be confirmed...

Subscription 28 cancelled.