{"id":20411515,"url":"https://github.com/hellwolf/super-lobster","last_synced_at":"2025-08-11T16:12:58.034Z","repository":{"id":154067979,"uuid":"476787822","full_name":"hellwolf/super-lobster","owner":"hellwolf","description":"Make Charles Hopkins's lobster super again.","archived":false,"fork":false,"pushed_at":"2022-04-01T16:20:36.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-04T04:50:18.375Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hellwolf.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-01T16:08:30.000Z","updated_at":"2022-04-01T16:09:21.000Z","dependencies_parsed_at":"2023-05-18T12:30:21.902Z","dependency_job_id":null,"html_url":"https://github.com/hellwolf/super-lobster","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hellwolf/super-lobster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellwolf%2Fsuper-lobster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellwolf%2Fsuper-lobster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellwolf%2Fsuper-lobster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellwolf%2Fsuper-lobster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hellwolf","download_url":"https://codeload.github.com/hellwolf/super-lobster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellwolf%2Fsuper-lobster/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269917392,"owners_count":24496082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"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-15T05:52:52.607Z","updated_at":"2025-08-11T16:12:58.013Z","avatar_url":"https://github.com/hellwolf.png","language":"Haskell","readme":"# Lobster Challenge\n\n![Charles and his Super lobster](lobster.jpg \"Charles and his lobster\")\n\nCharles has a Super lobster, but the poor creature does not yet have a name.\nLet's use a simple Plutus Smart Contract on Cardano to help Charles find a name for his lobster!\n\nWe start with a [list of names](names.md) and a \"secret random\" number, which we will only reveal in the end.\nThen we need the Community's help! We need 500 Community members who are willing to help name the lobster by\ncreating transactions which will add their own \"random\" number (from 1 to 100) to the current total.\n\nIn the end, we will reveal our own \"secret random\" number, add it to the total provided by the Community,\nand use the result (after taking the remainder after division by the number of available names) as an index\ninto the list of names to pick the lobster name.\n\n## Native Tokens\n\nWe use three distinct native tokens to help us name the lobster:\n\n| Policy                                     | Policy Id                                                  | Token Name       | Purpose                             |\n| ------------------------------------------ | ---------------------------------------------------------- | ---------------- | ----------------------------------- |\n| [script](scripts/nft-mint-policy.plutus)   | `cc7888851f0f5aa64c136e0c8fb251e9702f3f6c9efcf3a60a54f419` | `LobsterNFT`     | Identifies the relevant UTxO.       |\n| [script](scripts/other-mint-policy.plutus) | `fda1b6b487bee2e7f64ecf24d24b1224342484c0195ee1b7b943db50` | `LobsterCounter` | Stores the current \"random\" number. |\n| [script](scripts/other-mint-policy.plutus) | `fda1b6b487bee2e7f64ecf24d24b1224342484c0195ee1b7b943db50` | `LobsterVotes`   | Counts the number of votes.         |\n\nThe first one, `LobsterNFT`, is an NFT and used to identified the \"correct\" UTxO \"sitting\" at the contract address.\n(Recall that _anybody_ can send _anything_ _anywhere_ at _anytime_, so we can't prevent people from creating other UTxO's at the script address.\nThe UTxO we care about is the one holding the NFT.)\n\nThe second one, `LobsterCounter`, stores the current \"random\" number. It starts at zero when the contract is deployed,\nand each \"vote\" can add a number of tokens between 1 and 100.\nOnce 500 people have \"voted\", we add our own secret number, which we picked before deploying the contract and which is a parameter to the contract and hence encoded in the script address. Finally we take the rest of dividing the sum by the number of names in the list of possible names.\nThis will be the final amount of `LobsterCounter` tokens \"sitting\" at the script address, and it will indicate the index of the chosen lobster name.\n\nThe third token, `LobsterVotes`, is used to count the number of \"votes\".\nEach time a user interacts with the contract and increases the amount of `LobsterCounter` tokens by a \"random\" number,\nThe amount of `LobsterVotes` tokens at the script UTxO will go up by one.\nOnce 500 people have \"voted\", voting stops, and we will set the final result with a last transaction,\nwhich will bring the amount of `LobsterVotes` tokens to its ultimate value of 501.\n\n## Script\n\nThe validator for the naming contract is paramterized by six parameters:\n\n| Parameter  | Value                              | Explanation                     ]\n| ---------  | ---------------------------------- | ------------------------------- |\n| Seed       | TO BE REVEALED                     | Our own \"random\" number.        |\n| NFT        | `LobsterNFT`token (see above)      | Token identifying the UTxO.     |\n| Counter    | `LobsterCounter` token (see above) | Token tracking \"random\" number. |\n| Votes      | `LobsterVotes` token (see above)   | Token counting votes.           |\n| Name Count | 1219                               | Number of available names.      |\n| Vote Count | 500                                | Number of votes.                |\n\nWe will reveal the \"seed\", our own \"random\" contribution, in the end,\nwhen we finalize the contract.\n\nUsing these parameter values, we get a [script](scripts/lobster.plutus) with script address `addr1w8433zk2shufk42hn4x7zznjjuqwwyfmxffcjszw5l2ulesdt3jff`.\n\n## Example\n\nLet's look at an example and assume our own \"secret random\" number is 42.\n\nVoting might progress as follows:\n\n| `LobsterCounter` | `Lobster Votes` | Comment |\n| ----------------:| ---------------:| ------- |\n|                0 |               0 | In the beginning, there have been no votes, and the counter starts at zero.                                     |\n|               13 |               1 | The first Community member votes and adds 13 to the counter.                                                    |\n|              113 |               2 | The second Community member adds 100.                                                                           |\n|              114 |               3 | The third Community member adds 1.                                                                              |\n|              ... |             ... | More Community members add their own numbers.                                                                   |\n|            24782 |             500 | The last vote has been cast, which brought the counter to 24782.                                                |\n|              444 |             501 | We add our own secret, 42, and get 24824. Dividing this by 1219, the number of names, gives a remainder of 444. |\n\nIn this example, the lobster will get the name with index 444, which happens to be __Stewart__.\n\n## Voting\n\nWe will kick off the process by minting the `LobsterNFT` NFT and creating a UTxO at the script address,\nwhich contains the NFT, but neither `LobsterCounter` nor `LobsterVotes` tokens yet,\nbecause the counter starts at zero, and there have been no votes.\n\nTo vote, you have to create a transaction that spends the UTxO at the script address holding the NFT\nand creates a new UTxO at the same address, which holds the same NFT,\none more `LobsterVotes` tokens than before and\na number between 1 and 100 more `LobsterCounter` tokens than before.\n\nThis means that this transaction will have to mint `LobsterVotes` and `LobsterCounter` tokens,\nbut that's fine: The minting policy of those tokens allows arbitrary minting.\n\nThe Plutus script defining the script address will make sure that all constraints are satisfied:\n\n - The NFT has to be present in both the spent UTxO and the newly created one.\n - The amount of `LobsterVotes` tokens must be smaller than 500 in the beginning, and it must increase by one.\n - The amount of `LobsterCounter` tokens must go up by a number between 1 and 100.\n\nYou can use this [Bash script](scripts/lobster-contribute.sh) to create, sign and submit a suitable transaction.\nThis assumes that you have a node running, the command line interface `cardano-cli` available and that your node socket is called `node.socket`.\nThe script expects seven arguments:\n\n - A UTxO with some funds to provide collateral and pay for transaction fees.\n - The current script UTxO.\n - The filename of a file containing your address - this is where the change will go.\n - The filename of the file containing your signing key.\n - The current amount of `LobsterCounter` tokens.\n - The new amount of `LobsterCounter` tokens (which must be 1-100 higher than the current amount).\n - The current amount of `LobsterVotes` tokens (which should be less than 500).\n\nI also recorded an [Explainer Video](https://youtu.be/6xEAnMaov3E).\n\n## Finalization\n\nOnce 500 votes have been cast, we will submit a final transaction to get the ultimate result and record it as the final amount of `LobsterCounter` tokens.\nAs stated above, we will add our own secret random number to the total and take the remainder after division by the number of names in our list.\nWe can't \"cheat\" at this step, because the Plutus contract has been paramterized by our number, and the contract will enforce that we calculate the final value correctly.\n\n## Code\n\nYou can look at the Plutus code [here](src/Cardano/PlutusLobster/LobsterScript.hs),\nwhere you will find the minting policies for the used native tokens and the validator enforcing the contract logic.\n\nYou can build the code with `cabal build`.\n\n## Result\n\nThe 500 votes are in! The final counter after 500 votes was 22933. Adding our own \"random\" number, which was 582757474857012117487873, gives 582757474857012117510806.\nTaking the remainder after division by 1219, the number of potential names, gives __522__.\nLooking into the [list of names](names.md), we see that this index points to the name __Logan__.\n\nCharles' lobster finally has his name!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellwolf%2Fsuper-lobster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhellwolf%2Fsuper-lobster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellwolf%2Fsuper-lobster/lists"}