{"id":19107490,"url":"https://github.com/smartcontractkit/quickstarts-giveaway","last_synced_at":"2026-06-17T12:32:15.112Z","repository":{"id":193368756,"uuid":"673521552","full_name":"smartcontractkit/quickstarts-giveaway","owner":"smartcontractkit","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-15T03:45:58.000Z","size":1225,"stargazers_count":6,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-22T10:33:24.041Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smartcontractkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-01T20:24:20.000Z","updated_at":"2024-02-06T02:40:37.000Z","dependencies_parsed_at":"2023-09-07T23:44:37.046Z","dependency_job_id":null,"html_url":"https://github.com/smartcontractkit/quickstarts-giveaway","commit_stats":null,"previous_names":["smartcontractkit/quickstarts-giveaway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/smartcontractkit/quickstarts-giveaway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fquickstarts-giveaway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fquickstarts-giveaway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fquickstarts-giveaway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fquickstarts-giveaway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcontractkit","download_url":"https://codeload.github.com/smartcontractkit/quickstarts-giveaway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fquickstarts-giveaway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34449277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T04:12:46.575Z","updated_at":"2026-06-17T12:32:15.096Z","avatar_url":"https://github.com/smartcontractkit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Giveaway Manager (Automation + VRF)\n\n## I. About\n\nThe app is a highly configurable proof of concept for provably-fair giveaways using Chainlink Automation and VRF. It is capable of drawing winners from a CSV list or onchain entries utilizing Chainlink VRF Direct Funding and Automation. Fulfillment is not included and this app is for provably fair selection purposes only.\n\n![image](https://i.imgur.com/lCIAVrR.png)\n\nRecommended Networks:\n\n- Ethereum Mainnet\n- Ethereum Goerli\n- Polygon Mainnet\n- Polygon Mumbai\n\nIt is recommened to start with a testnet deployment to get familar with the functionality before deploying to mainnets.\n\n## II. Pre-requisites\n\n### 1. Clone repo\n\n```bash\n$ git clone https://github.com/smartcontractkit/quickstart-giveaway.git\n```\n\n### 2. Create block explorer API key\n\n- [Etherscan](https://docs.etherscan.io/getting-started/viewing-api-usage-statistics)\n- [Polyscan](https://docs.polygonscan.com/getting-started/viewing-api-usage-statistics)\n\n### 3. Setup contracts environment variables\n\nSetup an `env` variables\n\n```bash\n# \u003croot\u003e/contracts\n$ touch .env\n$ open .env\n# Consider using a secure env management package instead\n# Make sure this is untracked if you're going to push to your own repo\n```\n\n```bash\n# Do NOT use quotes to assign values!\n\n# Network RPCs\nexport RPC_URL=\n\n# Private key for contract deployment\nexport PRIVATE_KEY=\n\n# Explorer API key used to verify contracts\nexport EXPLORER_KEY=\n```\n\n### 4. Setup Wallet\n\nInstall any wallet to your browser (currently supports Metamask)\n\n## III. Setup (for public network deployments)\n\n### 1. Setup Foundry\n\n[Installation instructions](https://book.getfoundry.sh/getting-started/installation)\n\n```bash\n# Download foundry\n$ curl -L https://foundry.paradigm.xyz | bash\n\n# Install foundry\n$ foundryup\n\n# (Mac) Install anvil (prereq: Homebrew)\n$ brew install libusb\n```\n\n### 2. Install contract dependencies if changes have been made to contracts\n\n```bash\n# \u003croot\u003e/contracts\n$ make install\n```\n\n### 4. Deploy contract\n\n```bash\n# \u003croot\u003e/contracts\n$ make deploy\n```\n\n**Note:** Save the deployed contract address from your terminal output, you'll need for step 6.\n\n### 5. Install UI dependencies\n\n```bash\n# \u003croot\u003e/client\n# (Mac) you may need to run 'source ~/.nvm/nvm.sh'\n$ nvm use\n$ yarn\n```\n\n### 6. Run UI\n\nPrepare your UI `env` variables for export (needed for each time you want to run UI):\n\n- Giveaway Contract Manager Address from Step 4 \"Deploy Contract\"\n- Token Contract Addresses can be found [here](https://docs.chain.link/resources/link-token-contracts)\n- Keeper Registry Contract Addresses (currently only Automation v1.2 supported): `0x02777053d6764996e594c3E88AF1D58D5363a2e6` \n\n```bash\n# \u003croot\u003e/client/packages/ui\n# run these commands to set up your env vars (do not use quotes to assign values):\n$ export UI_GIVEAWAY_MANAGER_CONTRACT_ADDRESS=\n$ export UI_LINK_TOKEN_CONTRACT_ADDRESS=\n$ export UI_KEEPER_REGISTRY_CONTRACT_ADDRESS=\n$ yarn start\n```\n\n### 7. View UI\n\n- Open browser at [localhost:3005](localhost:3005)\n\n## IV. Testing\n\n### 1. Test Contracts\n\n```bash\n# \u003croot\u003e/contracts\nmake test-contracts-all\n```\n\n### 2. Test UI\n\n```bash\n# \u003croot\u003e/client/packages/ui\n$ yarn test\n$ yarn tsc\n$ yarn lint\n$ yarn prettier\n```\n\n### 8. Notes\n\n#### 1. Balance Amounts\n\nAs a creator of a giveaway, the minimum token requirments are needed to ensure that your giveaway is created and finished without issues. All unused LINK token amounts are able to be withdrawn after completion of giveaway.\n\n- 5.1 LINK\n  - 0.1 (VRF request)\n  - 5 (Automation subscription)\n\n#### 2. Giveaway Status\n\nAfter picking winners is initiated in the UI, the status of the giveaway is moved to `pending`. Each subsequent block is then checked to see if the VRF request has been finished and winners picked. Once found, the status is automatically moved to `finished`. The winners are then able to be viewed and leftover LINK is able to be withdrawn.\n\n#### 3. Developer Integration for Entering Dynamic Giveaway\n\nThe Giveaway contract is able to be integrated with any application that is able to send a transaction to the contract. The user will need to call the `enterGiveaway` function with the following parameters:\n\n- `giveawayId` - The ID of the giveaway that the user is entering\n- `entries` - The amount of entries the user is purchasing\n- `proof` The merkle proof of the user's entry if the giveaway is permissioned\n\nThis is how the UI in this repo calls the `enterGiveaway` function using `wagmi`:\n\n```javascript\nexport const enterGiveaway = async (params: contracts.EnterGiveawayParams) =\u003e {\n  try {\n    const { id, proof, fee } = params\n    const config = await prepareWriteContract({\n      address: giveawayManagerContractAddress,\n      abi: giveawayManagerABI,\n      functionName: 'enterGiveaway',\n      overrides: {\n        value: ethers.utils.parseEther(fee)\n      },\n      args: [id, params.entries ? params.entries : 1, proof ? proof : []]\n    })\n    const data = await writeContract(config)\n    return data\n  } catch (error: any) {\n    throw new Error(`Error entering giveaway: ${error.message}`)\n  }\n}\n\nexport interface EnterGiveawayParams {\n  id: number\n  entries?: number\n  proof?: string[]\n  fee: string\n}\n```\n\u003e :warning: **Disclaimer**: \"This repository represents an example of using a Chainlink product or service and is provided to help you understand how to interact with Chainlink’s systems and services so that you can integrate them into your own. This template is provided “AS IS” and “AS AVAILABLE” without warranties of any kind, has not been audited, and may be missing key checks or error handling to make the usage of the product more clear. Do not use the code in this example in a production environment without completing your own audits and application of best practices. Neither Chainlink Labs, the Chainlink Foundation, nor Chainlink node operators are responsible for unintended outputs that are generated due to errors in code.\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fquickstarts-giveaway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcontractkit%2Fquickstarts-giveaway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fquickstarts-giveaway/lists"}