{"id":13425695,"url":"https://github.com/cusma/algonim","last_synced_at":"2026-01-22T19:12:46.312Z","repository":{"id":48227182,"uuid":"266345966","full_name":"cusma/algonim","owner":"cusma","description":"AlgoNim, the first Algorand game","archived":false,"fork":false,"pushed_at":"2021-08-04T18:29:51.000Z","size":313,"stargazers_count":26,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-10T17:59:56.446Z","etag":null,"topics":["algorand","algorand-standard-assets","algorand-teal","asa","asa-asc1-architecture","asc1","atomic-swap","atomic-transfers","bet-escrows","blockchain","blockchain-technology","cryptography","game","nim","smart-contract","teal"],"latest_commit_sha":null,"homepage":"","language":"Python","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/cusma.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}},"created_at":"2020-05-23T13:49:47.000Z","updated_at":"2024-05-29T18:28:21.000Z","dependencies_parsed_at":"2022-08-27T15:00:32.983Z","dependency_job_id":null,"html_url":"https://github.com/cusma/algonim","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cusma%2Falgonim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cusma%2Falgonim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cusma%2Falgonim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cusma%2Falgonim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cusma","download_url":"https://codeload.github.com/cusma/algonim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243790948,"owners_count":20348378,"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","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":["algorand","algorand-standard-assets","algorand-teal","asa","asa-asc1-architecture","asc1","atomic-swap","atomic-transfers","bet-escrows","blockchain","blockchain-technology","cryptography","game","nim","smart-contract","teal"],"created_at":"2024-07-31T00:01:16.933Z","updated_at":"2026-01-22T19:12:46.288Z","avatar_url":"https://github.com/cusma.png","language":"Python","funding_links":[],"categories":["Learning Resources","Community Resources"],"sub_categories":["Projects"],"readme":"```\n      _       __                 ____  _____   _               \n     / \\     [  |               |_   \\|_   _| (_)              \n    / _ \\     | |  .--./)  .--.   |   \\ | |   __   _ .--..--.  \n   / ___ \\    | | / /'`\\;/ .'`\\ \\ | |\\ \\| |  [  | [ `.-. .-. | \n _/ /   \\ \\_  | | \\ \\._//| \\__. |_| |_\\   |_  | |  | | | | | | \n|____| |____|[___].',__`  '.__.'|_____|\\____|[___][___||__||__]\n                 ( ( __))                                      \n                                                       by cusma\n```\n# AlgoNim: let's play a crypto-Nim on Algorand from the CLI\n\n## What's Nim?\n[**Nim**](https://en.wikipedia.org/wiki/Nim) is a very simple mathematical game of strategy for two players. With a lot of imagination let's name them **Alice** and **Bob**.\n\nJust to be fair from the very beginning: Nim is a **zero-sum game** and has been **\"mathematically solved\"**, this means that exists an **\"easily calculated\"** perfect strategy to determine which player will win and what winning moves are open to that player.\n\n**So if Alice is a computer, Bob better avoid betting on winning the game.**\n\n## What's AlgoNim?\n**AlgoNim** is a cryptographic version of Nim that runs on [Algorand](https://algorand.foundation/) Layer 1, directly on the Pure Proof of Stake consensus protocol, so nobody can cheat. The game implementation takes advantage of all the features introduced in Algorand 2.0 protocol: [**Algorand Standard Assets (ASA)**](https://developer.algorand.org/docs/features/asa/), [**Atomic Transfers (AT)**](https://developer.algorand.org/docs/features/atomic_transfers/) and [**Algorand Smart Contracts (ASC1)**](https://developer.algorand.org/docs/features/asc1/) using Algorand  [**Python SDK**](https://developer.algorand.org/docs/reference/sdks/#python) +  [**PyTeal**](https://github.com/algorand/pyteal). PyTeal is a binding for [**TEAL**](https://developer.algorand.org/docs/features/asc1/teal_overview/), the **stateless bytecode stack based** language for ASC1, in this sense AlgoNim is a truly stateless game.\n\nThrough the **seamless interaction** between Algorand Python SDK and PyTeal, AlgoNim **automatically writes** and initializes a **dedicated set of stateless TEAL ASC1s and ASAs** for each match. The whole match set-up **takes few seconds** and **costs about 0.008 ALGOS** for transactions fees. AlgoNim accounts initialization and opt-in **require minimum balances**, so the Dealer needs 0.8 ALGO that can be refunded by slightly enhancing the TEAL ASCs1 making them more cost-efficient. Considerng that a new ASA + ASC1 architecture is generated for each match, **this time/cost performance is quite impressive if compared to other blockchains**.\n\nAlgoNim is played entirely from the **command line interface**. Find other AlgoNim players: https://t.me/algonim\n\n## AlgoNim rules\nAlgoNim is based on **Nim's \"normal\" single heap variant**. Alice is the player who creates the match: she is the **Dealer** and sets up the game table. Bob is the **Opponent**.\n\nRules are trivial:\n1. The Dealer chooses a heap of **N** pieces to be palced on the game table for the match;\n2. The Dealer chooses the number **M** of pieces that can be removed at the most from the game table in each turn;\n3. Alice and Bob choose who moves first;\n4. On each turn each player removes **at least 1** and **at the most M** pieces from the game table;\n\n**Who removes the last piece of the heap form the table wins the match!**\n\nAlice and Bob may choose **betting** some ALGOs for the match. Further implementations will accept **AlgoNim ASA Score Points** other then the betting reward for the matches, this will enable an **AlgoNim global ranking** too!\n\n## Install AlgoNim\n### Step 1 - Python modules\nAlgoNim uses the following Python3 modules:\n1. `msgpack`\n2. `docopt`\n3. `algosdk`\n4. `pyteal`\n\nso you need to install them (if not already present):\n\n```bash\n$ pip3 install --upgrade msgpack\n$ pip3 install --upgrade docopt\n$ pip3 install --upgrade py-algorand-sdk\n$ pip3 install --upgrade pyteal\n```\n\n### Step 2 - Environment setting\nTo run AlgoNim smoothly you need to set the following environmental variables:\n```bash\n$ export ALGORAND_DATA=/path/to/node/data\n$ export PATH=/path/to/node/:$PATH\n```\nAttention: setting `$ALGORAND_DATA` on your node you choose playing AlgoNim on MainNet, TestNet or BetaNet.\n\n### Step 3 - AlgoNim files\nCopy following AlgoNim files into your `node` directory (the same of `goal`):\n\n1. `algonim.py`\n2. `algonim_asa.py`\n3. `algonim_asc1.py`\n4. `algonim_moves.py`\n5. `algonim_lib.py`\n\n## How to play\nPlaying AlgoNim from your CLI is pretty easy, just ask for help:\n\n**Input**\n```bash\n$ python3 algonim.py --help\n```\n**Output**\n```\nAlgoNim, the first crypto-mini-game on Algorand! (by cusma)\nUsage:\n  algonim.py setup \u003cdealer_mnemonic\u003e \u003copponent_address\u003e \u003chours_duration\u003e\n                   [--bet-amount=\u003cba\u003e] [--pieces=\u003cps\u003e] [--max-removal=\u003cmr\u003e]\n  algonim.py join \u003copponent_mnemonic\u003e\n  algonim.py play \u003cplayer_mnemonic\u003e \u003casa_pieces_amount\u003e\n  algonim.py status \u003cplayer_address\u003e\n  algonim.py close \u003cplayer_address\u003e\n  algonim.py [--help]\n\nCommands:\n  setup    Dealer sets up a new AlgoNim match.\n  join     Opponent joins the match.\n  play     Play your turn.\n  status   Display current match status.\n  close    Close expired AlgoNim Bet Escrows.\n\nOptions:\n  -b \u003cba\u003e --bet-amount=\u003cba\u003e     Set the bet amount in microAlgos\n                                [default: 0].\n  -p \u003cps\u003e --pieces=\u003cps\u003e         Set the total amount of pieces on game table\n                                [default: 21].\n  -m \u003cmr\u003e --max-removal=\u003cmr\u003e    Set maximum amount of pieces removal\n                                [default: 4].\n  -h --help\n```\n\n### Step 1 - Match set up (Dealer)\nIn the first step the Dealer sets up the match, generating the ASAs + ASC1s game architecture. To set up the match the Dealer may choose the following options (or left them void for default values otherwise):\n1. `[--bet-amount=\u003cba\u003e]` is the bet proposal expressed in microALGO;\n2. `[--pieces=\u003cps\u003e]` is the number of pieces that the Dealer distributes on the Game Table;\n3. `[--max-removal=\u003cmr\u003e]` is the maximum number of pieces that can be removed from the Game Table on each turn by the players;\n\n**Input**\n```bash\n$ python3 algonim.py setup \u003cdealer_mnemonic\u003e NMZRQMXXYSRKVG4ZYJ5OUIN3AOLWJ2ZB5GVIGECAYM6G77D23MPA4BRP6I 2 20000000 21 4\n```\n**Output**\n```\n              _       _         \n  /\\/\\   __ _| |_ ___| |__    _ \n /    \\ / _` | __/ __| '_ \\  (_)\n/ /\\/\\ \\ (_| | || (__| | | |  _ \n\\/    \\/\\__,_|\\__\\___|_| |_| (_)\n                                \nMATCH DURATION:\t\t 120.0 min\nPIECES ON GAME TABLE:\t 21 \n\nRULES:\n1. Players on each turn must remove at least 1 ASA Piece\n2. Players on each turn must remove at most 4 ASA Piece\n3. Who removes the last ASA Piece form the Game Table wins the match!\n\nPlayer 1 - Dealer:\tSVMHAG6PLL27YYGQX4ETEIZ2GHLSO6M5ICU2MBJVKMDT2ERPNSE27OGWIE\nPlayer 2 - Opponent:\tNMZRQMXXYSRKVG4ZYJ5OUIN3AOLWJ2ZB5GVIGECAYM6G77D23MPA4BRP6I \n\nAlgoNim ASA Pieces ID:\t 7329523\nAlgoNim ASA Turn ID:\t 7329527 \n\nAlgoNim Sink Account:\t\t\t      7EUFKLR636O34XW2ZRMTVOCQAXIHUDEEKIY4ZPWAGDRU6A5AONKVN5K4R4\nAlgoNim Game Table Account:\t\t      JBASDWK7MQNRCYUDZBBGR4DFHEGQTCSZQWNUMW4O2XBNON5CFLWALGKJCA\nAlgoNim Bet Escrow Player 1 Account:\t      PUEKG6EPXF2HMUHB3GTTODXBGUXZX26YK36SJHU7X3ZPQWSKZXUZJAZT3Q\nAlgoNim Bet Escrow Player 2 Account:          W6YG5653UWDU4XTSK2767FHLQOTLXGRG53ZJGV6SEVTSMWOMJOAAMBGTX4\n\nSend 'algonim.match' file to your opponent join the match!\n\nMay the best win!\n\n```\nThe scripts generates both the `*.teal` and `*.tealc` ASC1s files and the `algonim.match` in which match's data are packed. The Dealer than sends `algonim.match` to the Opponent.\n\n### Step 2 - Join the match (Opponent)\nTo join the match the Opponent must decide whether accept the Dealer bet proposal or not. Accepting the proposal the Opponet will Opt-In the match's ASAs and fund both the Bet Escrows with the same amount issuing an Atomic Transfer (already signed by the Dealer).\n\n**Input**\n```bash\n$ python3 algonim.py join \u003copponent_mnemonic\u003e\n```\n**Output**\n```\n      _       __                 ____  _____   _               \n     / \\     [  |               |_   \\|_   _| (_)              \n    / _ \\     | |  .--./)  .--.   |   \\ | |   __   _ .--..--.  \n   / ___ \\    | | / /'`\\;/ .'`\\ \\ | |\\ \\| |  [  | [ `.-. .-. | \n _/ /   \\ \\_  | | \\ \\._//| \\__. |_| |_\\   |_  | |  | | | | | | \n|____| |____|[___].',__`  '.__.'|_____|\\____|[___][___||__||__]\n                 ( ( __))                                      \n                                                       by cusma\n                                                               \n  Welcome to AlgoNim, the first crypto-mini-game on Algorand!  \n\nThe Dealer wants to bet 20.0 ALGO.\nDo you want to join the match? [y/N]\n```\nMatch's ASAs Opt-In and betting AT.\n\n### Step 3 - Play turn (Dealer or Opponent)\nTo play a turn the Player must own the AlgoNim ASA Turn. With `algonim.py play` players may play both a regular turn and the last turn, closing the match and claiming the rewards locked in the Bet Escrows Account.\n\n**Input**\n```bash\n$ python3 algonim.py play \u003cplayer_mnemonic\u003e 4\n```\n**Output**\n```\nRemoving 4 pieces from the Game table...\n```\nPlay Turn Atomic Transfer consists of:\n1. Asset Send of 1 ASA Turn to the other player;\n2. Asset Send of an amount **P** (1 \u003c= P \u003c= M) ASA Pieces from the Game Table Account to Sink Account;\n\nOR\n\nPlay Last Turn Atomic Transfer consists of:\n1. Asset Send of 1 ASA Turn to the other player;\n2. Asset Send of an amount **P** (1 \u003c= P \u003c= M) ASA Pieces from the Game Table Account to Sink Account;\n3. Asset Send of ASA Pieces **total supply** from Sink Account to winner account;\n4. Close Bet Escrow Accounts claiming the betting rewards;\n\n### AlgoNim match's status\nEach player can check the current match's status with `algonim.py status`:\n\n**Input**\n```bash\n$ python3 algonim.py status NMZRQMXXYSRKVG4ZYJ5OUIN3AOLWJ2ZB5GVIGECAYM6G77D23MPA4BRP6I\n```\n**Output**\n```\nMATCH TOTAL PIECES:\t\t21\nPIECES ON THE GAME TABLE:\t17\nIt's your turn! Play your best move!\n\nOPPONENT BET ESCROW AMOUNT:\t 20100000\nYOUR BET ESCROW AMOUNT:\t\t 20100000\nYour Bet Escrow is still locked. 82 blocks left!\n```\nDisplays ASA Pieces total amount for this match, ASA Pieces currently on the Game Table, Player's Turn and Bet Escrows status.\n\n### Bet Escrows closing\nAt the end of the match **the winner can claim its own bet amount back** closing the Bet Escrow when it expires with `algonim.py close`:\n\n**Input**\n```bash\n$ python3 algonim.py close NMZRQMXXYSRKVG4ZYJ5OUIN3AOLWJ2ZB5GVIGECAYM6G77D23MPA4BRP6I\n```\n\nIf one of the players does not act for long time, both players can close their expired Bet Escrows claiming their own bets back.\n\n## Open future implementations\n1. Improving robustness of Bet Escrows (preventing players to stop the game in the middle simply waiting Bet Escrows expiry);\n2. Freezing match’s ASAs for anyone but the players;\n3. Automatically destroying match’s ASAs at the end of the game;\n4. Adding ASA AlgoNim Score in the Sink from Scores Pool as reward for the winner;\n5. Implementing a \"Multi-heaps\" variant;\n6. Implementing a \"Championship\" mode (2 out of 3 matches).\n\n## Troubleshooting\n\n### Issue with `KeyError: 'microalgo_bet_amount'`\n\nThis issue arises if you do not use the latest version of `msgpack`.\n`msgpack` version 1.0.0 is needed.\nRun: \n```bash\n$ pip3 install --upgrade msgpack\n```\n\n## Contact\nFor any issue, improvement proposal or comment please reach me out at: algonim.cusma@gmail.com\n\n## Tip the Dev\n\nIf you enjoyed AlgoNim or find it useful as free and open source learning example, consider tipping the Dev:\n\n`XODGWLOMKUPTGL3ZV53H3GZZWMCTJVQ5B2BZICFD3STSLA2LPSH6V6RW3I`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcusma%2Falgonim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcusma%2Falgonim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcusma%2Falgonim/lists"}