From 9323f10e4de2418b6fab32b7f757790c1a60093e Mon Sep 17 00:00:00 2001
From: stubbsta <tanya.steyn22@gmail.com>
Date: Fri, 16 Jan 2026 09:28:11 +0200
Subject: [PATCH] Add token management interface

---
 tools/__init__.py                             |   1 +
 tools/token_management/README.md              |  91 +++++++++
 .../__pycache__/interactions.cpython-310.pyc  | Bin 0 -> 3846 bytes
 tools/token_management/interactions.py        | 175 ++++++++++++++++++
 4 files changed, 267 insertions(+)
 create mode 100644 tools/__init__.py
 create mode 100644 tools/token_management/README.md
 create mode 100644 tools/token_management/__pycache__/interactions.cpython-310.pyc
 create mode 100644 tools/token_management/interactions.py

diff --git a/tools/__init__.py b/tools/__init__.py
new file mode 100644
index 0000000..4155709
--- /dev/null
+++ b/tools/__init__.py
@@ -0,0 +1 @@
+# This file makes the tools directory a Python package
diff --git a/tools/token_management/README.md b/tools/token_management/README.md
new file mode 100644
index 0000000..7529b4b
--- /dev/null
+++ b/tools/token_management/README.md
@@ -0,0 +1,91 @@
+# token-management
+
+Test utility for [TestStableToken](https://github.com/logos-messaging/logos-messaging-rlnv2-contract/blob/main/test/TestStableToken.sol) used in the Logos Messaging RLN v2 contract tests.
+
+Given the token contract address and an Ethereum JSON-RPC endpoint, it allows minting and transferring TestStableToken tokens.
+Given the contract address, it can also query allowances.
+
+Details about the use of TestStableToken can be found in the [TST README](https://github.com/logos-messaging/logos-messaging-rlnv2-contract/blob/main/test/README.md)
+
+## Configuration
+
+Set the following environment variables (or use a `.env` file):
+
+- `TOKEN_CONTRACT_ADDRESS`: The token contract proxy address
+- `RLN_CONTRACT_ADDRESS`: The RLN contract proxy address
+- `RLN_RELAY_ETH_CLIENT_ADDRESS`: The Ethereum JSON-RPC endpoint
+- `ETH_FROM`: The default user account address
+- `PRIVATE_KEY`: Private key for write operations (transfer, mint)
+
+## Usage
+
+The `interactions.py` script provides a CLI interface for all token operations.
+
+### Read-Only Commands (no PRIVATE_KEY required)
+
+Get total supply:
+```bash
+python3 tools/token_management/interactions.py total-supply
+```
+
+Get max supply:
+```bash
+python3 tools/token_management/interactions.py max-supply
+```
+
+Get contract owner:
+```bash
+python3 tools/token_management/interactions.py owner
+```
+
+Get implementation address:
+```bash
+python3 tools/token_management/interactions.py implementation
+```
+
+Get balance (defaults to USER_ACCOUNT_ADDRESS from env):
+```bash
+python3 tools/token_management/interactions.py balance
+python3 tools/token_management/interactions.py balance 0xYourAddress
+```
+
+Get allowance (defaults to USER_ACCOUNT_ADDRESS and RLN_CONTRACT_PROXY_ADDRESS):
+```bash
+python3 tools/token_management/interactions.py allowance
+python3 tools/token_management/interactions.py allowance 0xOwner 0xSpender
+```
+
+Check if address is a minter (defaults to USER_ACCOUNT_ADDRESS):
+```bash
+python3 tools/token_management/interactions.py is-minter
+python3 tools/token_management/interactions.py is-minter 0xAddress
+```
+
+### Write Commands (PRIVATE_KEY required)
+
+All write commands accept an optional `--private-key` flag to specify a custom private key. If not provided, the `PRIVATE_KEY` environment variable will be used.
+
+Transfer tokens:
+```bash
+python3 tools/token_management/interactions.py transfer 0xRecipient 100.5
+python3 tools/token_management/interactions.py transfer 0xRecipient 100.5 --private-key 0xYourPrivateKey
+```
+
+Mint tokens:
+```bash
+python3 tools/token_management/interactions.py mint 0xRecipient 1000
+python3 tools/token_management/interactions.py mint 0xRecipient 1000 --private-key 0xYourPrivateKey
+```
+
+Approve spender to use tokens:
+```bash
+python3 tools/token_management/interactions.py approve 0xSpender 500
+python3 tools/token_management/interactions.py approve 0xSpender 500 --private-key 0xYourPrivateKey
+```
+
+### Help
+
+View all available commands:
+```bash
+python3 tools/token_management/interactions.py --help
+```
diff --git a/tools/token_management/__pycache__/interactions.cpython-310.pyc b/tools/token_management/__pycache__/interactions.cpython-310.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..afccef3356b4984a49c8f5f879366b2a2328f105
GIT binary patch
literal 3846
zcmb6bU2hx5@%HXW9w~~ZZCQzIS!LSB37uHt_lM#*rYNd$?MNymC$U}*NA6NOiR7_+
zM@u$nps3o%0)3B*l8=7t?^*P%PX_wtx1y*!v!p0ewhQzQH#<8!xAU<xv*XOph7@@I
z`ghy@+nl2O11FQu6`0(I&plKXg({RZl|3BQCTXdADnVRpYAt<FCkoR~6@W_LM|J8O
zsC#~i`)L61fW!?N1l*8#h|T~Wlz5oV0v?*+pP><YiAL$=m+C&DSLjtbH^Q&c`Io-)
zRr=A0OQj#fJI%E~uMb!0jnRrq7wJv9G_}{l*&Y*IKYNEOvaiq>{e=E}>R+V(0;s=y
zhx+MzskeZ7QOD0lI(|OZF%G+)*?D{Hg)iXWY0Xjkm+$O|)H^^u^WJDDpe|pe?$7Rp
znab4uEDH|EDcOs#$l;~KC{Qjl|A4SCUHOx`7o`cB{DZQ0g{Ej4#;Y_#7h#;ESsI7&
z8qLu>jPtZWi!gpfSLs(UeoXJuuVGxE_vkk;UZ?kI3C0_2k**!7e<nQ5ZqhPaI8{zD
zn#hj);_I(53OD0K=s&Pp8pfHXV^Nbj9&0}p^SfIQE1PC{Yjd|+D({-5_4R6HXGh#l
zoUnW&nNMXa`FuK4uA~ZujY2w?XUVl%GLx<p6SZ1;Bauy}gi+c3*4(IWeTRQF(!~bN
zv24<^Xra)^H8ORUvucGxDxb<1>y1XER!pUGIWbp#^nSUCWG-9C7fRV;rf#LO*>t*K
z(T0_wnL;L0Y~+fmOsY~VY=}kNp;~!VdSapm<wp-Hn_~-}&mDMPXLV&InOIIOCzjKz
zg={7(X11#jzAx=o%!idHLfwA2EBvN&+-6(^EJ`_Z-MA|Bw$)-n_nvi_2-d8o)vmLx
zh6s#M5$M`&FO|&+qtR{GJ=<x=eZr_aZP&Bfp77i4PS<n!C2+h5I9*T9qBt{5x5L^L
z#09Np(>cbSH-u(-4(RdJYId10JZ`n!25RJX>vhmb=rzY_f`Xk6cb)<VWp%q{HC>?y
zAF5Iie)n0c20VV(<92(0D0;?oJgd3W?R1*Ygo+}pmeU0V^%ndD`_=1mYS`{~KtQEh
z*2#$9H}p!xZgrZh#oC@F?NoUL?a-{6T_=E@JsKcB_{#9P2>_mQNcyU$_4S@IAOq6(
z4U`u|QvCxcY%o)Mgp!_mRk@+;D6iDb*H}U00qIF_LfsR=Gyl5$GOTeZor<{XIcEKU
z)sNh6%N!k=(Cgq&9>WbZsUpXMD+#X@o(240TPp`ni><g`w^oCLS~+(3(H+h@j=OSf
z9d+-xcB|X8JcqA%;BFV-5o?<*t8MK|2dqdRfm(3h?sDgunAvBZIf{u}Ai?zmm?seu
zCOi*l9o0R1bU<)jI;a51w1cFhz)b^n=$a`<X+0Gjr41d$SK#M(fG1(#DFh1$P!>-k
z$RLOTi0k}I7$A;@F*jty73q*6$RWopS~3pEFMuR%SsL0>g!wzR1b~RPyul5Iw!pD!
zc&u`!d%nIOkKPNM9rK)W3iiFwJfo+bLVX%q5}dFk273+lUqozdlh9<qx{x}ick)UX
zA&7y|(euxc75{`7Ke=ET$9*sy-=Oa!Bt{JKK~wlD@cb{OKF9U3Qv55N-bL^=0t~Wq
zpK@fDr2BwO<qGD_I9KLjG93!TT!D-rn{oeyb8Z9YgmgUSI2p$Jv}h5uT@zEBNsC<6
zc%JYz80zp%J-8;15z~6|7~yzIK!O-L542B#Fg%`fffAEJ6vZHtCC7AS%|WlcK>-oM
z*J1deaE=<hD-PrE!{Q<+4(ioN*nMQKAlLx#|BAvq`LL)UijwtEDk`P?>Y@}hbbPA!
zVB*0AOx08Mh2oJzwXb=4-{(Oi07;=jC4{s%B~&|7`AtX=ohpA+7nHs+fLci5i~Bak
zTH+*~OB9NkQZl_(N|w^8WFnW#mkX&vrkGk^D;CzvrF12g$mh!CbUvLe6;p{)x?IX8
zvg_$WYHh9j8n2z#F#z^I-@bht56Y+&>Tz0V%sUX$i!KyBC~~IdoyV70ywDkJSGRtA
zGVTwwCTk1rfSurV={6ltXxuu!kOSfhI&S&~LBF|J=tJrp39C_}6TSn}sSLqnJu5Ko
z?_lC7eYh*Aik|Bc9tMx0=c1lU^;7bD;%SHaAr>4cp>VG#{XkDWG?3a4A~qn@CwW5D
z|567YD5?FKo(7mMxxzjDa294hFG2%7U;olT`APYUdP<1W^TBBtn|ucJ;GZA}19<-H
zQVcF^o5m(OiWsz1Hh0>1U&1Q4ty+`CY&XW)Z@V^UG}dr<?3mjgi#Z*}<(=v-+xKTR
z$TXohxYH88wgX*((Dp4?7y!1pU1!gOJGiHJvKos=h3dG%55C0?F7!RN4HeEE&L5(7
zj}XKGKzjoFnMdrIxLoVnO{ksNS`2Tn;XQs04`_mF4m*M%h&4MXS43TVzdgw!=42U$
z)1IP6fUtYMz3{>BZI5q*9&x`2cqb;_<<f~lht9*}-=K<q+@4X%aA3Iy7a~ZO*WUo6
zi-kN4H>&}6k`8Z}sKif<e~0`Las`733o-OpP!jC6X+963Win@1<4gQUT-1-D0hSRi
z{KNK_Ye45u5NsmH#hBmvVY5;l$NcrFj&(X80@dxZ`MCOMXyDxA9sI9c-g<oAk&0lY
zT23X*(%J(N{&shFdmFkr8+yTsW0SR3-s0FmaJ+ft6((;JS;1u`l{JoID#_d#+m3y!
zY4RE_ystzXcUunaHrYMAf?PD&kWTe$VGW%-e3$fF1mF45yF`{onEoabohOEF_(rd0
O;Hw*<P&BIQ|M@SMwWjm{

literal 0
HcmV?d00001

diff --git a/tools/token_management/interactions.py b/tools/token_management/interactions.py
new file mode 100644
index 0000000..08f1014
--- /dev/null
+++ b/tools/token_management/interactions.py
@@ -0,0 +1,175 @@
+import os
+from web3 import Web3
+from dotenv import load_dotenv
+
+# Load environment variables from .env if present
+load_dotenv()
+
+TOKEN_CONTRACT_PROXY_ADDRESS = os.getenv("TOKEN_CONTRACT_ADDRESS", "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512")
+TOKEN_CONTRACT_OWNER_ADDRESS = os.getenv("ETH_FROM", "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266")  # Replace with actual owner address
+RLN_CONTRACT_PROXY_ADDRESS = os.getenv("RLN_CONTRACT_ADDRESS", "0x0165878A594ca255338adfa4d48449f69242Eb8F")  # Replace with actual RLN contract address
+RPC_URL = os.getenv("RLN_RELAY_ETH_CLIENT_ADDRESS", "http://foundry:8545") #Replace 'foundry' with the containers actual IP or replace entirely with your own RPC URL
+USER_ACCOUNT_ADDRESS = os.getenv("ETH_FROM", "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266")  # Replace with actual user address
+CONTRACT_OWNER_PRIVATE_KEY = os.getenv("PRIVATE_KEY", "PK")  # Replace 'PK' with your private key or set in .env
+
+
+# Standard ERC20 ABI (truncated to main functions)
+ERC20_ABI = [
+    {"constant":True,"inputs":[{"name":"_owner","type":"address"}],"name":"balanceOf","outputs":[{"name":"balance","type":"uint256"}],"type":"function"},
+    {"constant":True,"inputs":[{"name":"_owner","type":"address"}, {"name":"_spender", "type":"address"}],"name":"allowance","outputs":[{"name":"allowance","type":"uint256"}],"type":"function"},
+    {"constant":False,"inputs":[{"name":"_to","type":"address"},{"name":"_value","type":"uint256"}],"name":"transfer","outputs":[{"name":"success","type":"bool"}],"type":"function"},
+    {"constant":False,"inputs":[{"name":"_spender","type":"address"},{"name":"_value","type":"uint256"}],"name":"approve","outputs":[{"name":"success","type":"bool"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"decimals","outputs":[{"name":"","type":"uint8"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"symbol","outputs":[{"name":"","type":"string"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"name","outputs":[{"name":"","type":"string"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"totalSupply","outputs":[{"name":"","type":"uint256"}],"type":"function"},
+    {"constant":False,"inputs":[{"name":"to","type":"address"},{"name":"amount","type":"uint256"}],"name":"mint","outputs":[],"type":"function"},
+    {"constant":True,"inputs":[{"name":"account","type":"address"}],"name":"isMinter","outputs":[{"name":"","type":"bool"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"maxSupply","outputs":[{"name":"","type":"uint256"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"owner","outputs":[{"name":"","type":"address"}],"type":"function"},
+    {"constant":True,"inputs":[],"name":"implementation","outputs":[{"name":"","type":"address"}],"type":"function"}
+]
+
+w3 = Web3(Web3.HTTPProvider(RPC_URL))
+contract = w3.eth.contract(address=Web3.to_checksum_address(TOKEN_CONTRACT_PROXY_ADDRESS), abi=ERC20_ABI)
+
+
+
+def get_balance(address):
+    balance = contract.functions.balanceOf(Web3.to_checksum_address(address)).call()
+    decimals = contract.functions.decimals().call()
+    return balance / (10 ** decimals)
+
+def get_allowance(owner, spender):
+    allowance = contract.functions.allowance(Web3.to_checksum_address(owner), Web3.to_checksum_address(spender)).call()
+    decimals = contract.functions.decimals().call()
+    return allowance / (10 ** decimals)
+
+def transfer(to_address, amount, private_key=None):
+    decimals = contract.functions.decimals().call()
+    tx = contract.functions.transfer(Web3.to_checksum_address(to_address), int(amount * (10 ** decimals)))
+    return send_tx(tx, private_key)
+
+def mint(to_address, amount, private_key=None):
+    decimals = contract.functions.decimals().call()
+    tx = contract.functions.mint(Web3.to_checksum_address(to_address), int(amount * (10 ** decimals)))
+    return send_tx(tx, private_key)
+
+def approve(spender_address, amount, private_key=None):
+    decimals = contract.functions.decimals().call()
+    tx = contract.functions.approve(Web3.to_checksum_address(spender_address), int(amount * (10 ** decimals)))
+    return send_tx(tx, private_key)
+
+def is_minter(address):
+    return contract.functions.isMinter(Web3.to_checksum_address(address)).call()
+
+def get_total_supply():
+    return contract.functions.totalSupply().call()
+
+def get_max_supply():
+    return contract.functions.maxSupply().call()
+
+def get_owner():
+    return contract.functions.owner().call()
+
+# Read: get implementation contract address (proxy, EIP-1967)
+def get_implementation():
+    # EIP-1967 implementation slot
+    slot = int('0x360894A13BA1A3210667C828492DB98DCA3E2076CC3735A920A3CA505D382BBC', 16)
+    raw = w3.eth.get_storage_at(Web3.to_checksum_address(TOKEN_CONTRACT_PROXY_ADDRESS), slot)
+    # The address is stored right-aligned in 32 bytes
+    if len(raw) == 32:
+        return raw[-20:].hex()
+    return None
+
+# Helper: send transaction
+def send_tx(tx_func, private_key=None):
+    if private_key is None:
+        private_key = os.getenv("PRIVATE_KEY", "")
+    if not private_key or private_key == "PK":
+        raise ValueError("A valid PRIVATE_KEY is required for write operations. Provide it via parameter or environment variable.")
+    acct = w3.eth.account.from_key(private_key)
+    tx = tx_func.build_transaction({
+        'from': acct.address,
+        'nonce': w3.eth.get_transaction_count(acct.address),
+        'gas': 200000,
+        'gasPrice': w3.eth.gas_price
+    })
+    signed = acct.sign_transaction(tx)
+    tx_hash = w3.eth.send_raw_transaction(signed.rawTransaction)
+    print(f"Sent tx: {tx_hash.hex()}")
+    return tx_hash
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description='Token Management CLI')
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    # Read-only commands
+    subparsers.add_parser('total-supply', help='Get total token supply')
+    subparsers.add_parser('max-supply', help='Get max token supply')
+    subparsers.add_parser('owner', help='Get contract owner')
+    subparsers.add_parser('implementation', help='Get implementation contract address')
+
+    balance_parser = subparsers.add_parser('balance', help='Get token balance')
+    balance_parser.add_argument('address', nargs='?', default=USER_ACCOUNT_ADDRESS, help='Address to check (default: USER_ACCOUNT_ADDRESS from env)')
+
+    allowance_parser = subparsers.add_parser('allowance', help='Get token allowance')
+    allowance_parser.add_argument('owner', nargs='?', default=USER_ACCOUNT_ADDRESS, help='Owner address (default: USER_ACCOUNT_ADDRESS from env)')
+    allowance_parser.add_argument('spender', nargs='?', default=RLN_CONTRACT_PROXY_ADDRESS, help='Spender address (default: RLN_CONTRACT_PROXY_ADDRESS from env)')
+
+    minter_parser = subparsers.add_parser('is-minter', help='Check if address is a minter')
+    minter_parser.add_argument('address', nargs='?', default=USER_ACCOUNT_ADDRESS, help='Address to check (default: USER_ACCOUNT_ADDRESS from env)')
+
+    # Write commands
+    transfer_parser = subparsers.add_parser('transfer', help='Transfer tokens (requires PRIVATE_KEY)')
+    transfer_parser.add_argument('to', help='Recipient address')
+    transfer_parser.add_argument('amount', type=float, help='Amount to transfer')
+    transfer_parser.add_argument('--private-key', help='Private key (default: PRIVATE_KEY from env)')
+
+    mint_parser = subparsers.add_parser('mint', help='Mint tokens (requires PRIVATE_KEY)')
+    mint_parser.add_argument('to', help='Recipient address')
+    mint_parser.add_argument('amount', type=float, help='Amount to mint')
+    mint_parser.add_argument('--private-key', help='Private key (default: PRIVATE_KEY from env)')
+
+    approve_parser = subparsers.add_parser('approve', help='Approve spender to use tokens (requires PRIVATE_KEY)')
+    approve_parser.add_argument('spender', help='Spender address')
+    approve_parser.add_argument('amount', type=float, help='Amount to approve')
+    approve_parser.add_argument('--private-key', help='Private key (default: PRIVATE_KEY from env)')
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+    elif args.command == 'total-supply':
+        decimals = contract.functions.decimals().call()
+        supply = get_total_supply()
+        print(f"Total Supply: {supply / (10 ** decimals)}")
+    elif args.command == 'max-supply':
+        decimals = contract.functions.decimals().call()
+        supply = get_max_supply()
+        print(f"Max Supply: {supply / (10 ** decimals)}")
+    elif args.command == 'owner':
+        print(f"Owner: {get_owner()}")
+    elif args.command == 'implementation':
+        impl = get_implementation()
+        print(f"Implementation: 0x{impl}" if impl else "Implementation: Not found")
+    elif args.command == 'balance':
+        balance = get_balance(args.address)
+        print(f"Balance of {args.address}: {balance}")
+    elif args.command == 'allowance':
+        allowance = get_allowance(args.owner, args.spender)
+        print(f"Allowance: {allowance}")
+    elif args.command == 'is-minter':
+        result = is_minter(args.address)
+        print(f"{args.address} is minter: {result}")
+    elif args.command == 'transfer':
+        tx_hash = transfer(args.to, args.amount, getattr(args, 'private_key', None))
+        print(f"Transfer complete: {tx_hash.hex()}")
+    elif args.command == 'mint':
+        tx_hash = mint(args.to, args.amount, getattr(args, 'private_key', None))
+        print(f"Mint complete: {tx_hash.hex()}")
+    elif args.command == 'approve':
+        tx_hash = approve(args.spender, args.amount, getattr(args, 'private_key', None))
+        print(f"Approve complete: {tx_hash.hex()}")