# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } """A token that carries its own rules and keeps them without being asked. Every meme coin makes promises. Liquidity locked for six months, team tokens vesting, two percent of the treasury burned when we hit a milestone, the treasury returned to holders if the project goes quiet. Those promises live in a pinned Telegram message, and the pinned message is not connected to anything. Nobody enforces it, the creator can walk away from it, and the holder who believed it has no recourse. This is the other arrangement. **The rule is written into the token at launch, in plain words, and it cannot be edited afterwards by anyone including the creator.** When its condition is met, anybody at all can make the token carry it out, and the token cannot refuse. Why this needs a network that can read -------------------------------------- The conditions worth writing are not arithmetic on the token's own ledger. They are things like *the project's repository has had no commit in ninety days*, or *the published audit has expired*, or *the price has doubled against the pair we launched on*. A contract cannot evaluate any of those. It has no idea what a repository is. So the condition goes to the validators in the words its creator wrote, along with whatever page it names as the place to check, and they answer one question: has this happened yet. The **action** is not left to judgement. It is a fixed instruction the contract executes itself, in ordinary code, once the answer comes back MET. What "automatic" honestly means here ------------------------------------ No chain lets a contract wake itself up. There is no cron, and a rule nobody ever checks is a rule that never fires. So `tick` is open to everybody and pays whoever calls it out of the treasury. The guarantee is not that the token acts unprompted. It is that **when the condition is met, anybody in the world can make it act, and the creator cannot stop them.** No signature, no permission, no cooperation from the person who would least like it to happen. That is the part a promise in a pinned message has never had. Design notes ------------ *Rules are frozen at construction.* If the creator could add, edit or remove a rule after launch, a badge saying the token burns on a milestone would be worth exactly as much as the Telegram message it replaced. Nothing in this contract writes to `rules` after `__init__`. *One field goes to consensus.* The round answers `MET`, `NOT_MET` or `CANNOT_TELL` and validators must match that word exactly. Which rule fires, what it does, how much moves and who gets paid for the call are all worked out here in deterministic code. Every extra field bound into an equivalence rule costs agreement. *A page that will not load is not a met condition.* `CANNOT_TELL` changes nothing. Treating an unreachable page as proof would let anyone fire a rule by taking a site down, and would let a creator dodge one by doing the same. *Nothing inside the block reads storage.* Every value the round needs is read out here and passed in as a local, because reading `self` from inside a nondeterministic block is the one pattern that reliably stops rounds from completing. """ from genlayer import * from datetime import datetime, timezone import json import typing # What the round may answer. Compared with `==`, never with `in`, so no answer # can be mistaken for another by being a substring of it. MET = "MET" NOT_MET = "NOT_MET" CANNOT_TELL = "CANNOT_TELL" READINGS = (MET, NOT_MET, CANNOT_TELL) # What a rule may do when its condition is met. The judgement decides *whether*; # this list is the whole of *what*, and every one of them is arithmetic. BURN = "BURN" DISTRIBUTE = "DISTRIBUTE" ACTIONS = (BURN, DISTRIBUTE) WAITING = "WAITING" FIRED = "FIRED" MIN_CONDITION = 15 MAX_CONDITION = 400 MAX_URL = 300 MAX_PAGE = 4000 MAX_WHY = 300 MAX_RULES = 8 MAX_HOLDERS_IN_REPORT = 50 # What the caller of a successful tick is paid, in ten thousandths of the # treasury. Small enough not to be worth farming, large enough that somebody # watching a condition has a reason to be the one who calls. CALLER_SHARE = 50 def _now_iso() -> str: return datetime.now(timezone.utc).isoformat() def _addr(address) -> str: return str(address).lower() def _address(value: str) -> str: text = str(value).strip().lower() if not text.startswith("0x") or len(text) != 42: return "" for character in text[2:]: if character not in "0123456789abcdef": return "" return text def _clip(text: str, limit: int) -> str: text = str(text).strip() return text if len(text) <= limit else text[:limit] + " [...]" def _url(value: str) -> str: """An address a validator can be asked to fetch, or nothing. A rule with no url is allowed: its condition then turns on what the token can see about itself, which the round is given anyway. """ text = str(value).strip() if not text or len(text) > MAX_URL or " " in text: return "" if not text.startswith("https://") and not text.startswith("http://"): return "" rest = text.split("//", 1)[1] if "//" in text else "" if "." not in rest.split("/")[0] or len(rest.split("/")[0]) < 4: return "" return text def _whole(value) -> int: try: return int(str(value).strip()) except Exception: return -1 def _reading(raw: str) -> str: """The one word the round had to agree on, or nothing. An answer this contract does not recognise moves nothing and fires nothing. """ text = str(raw).strip() try: obj = json.loads(text[text.index("{"):text.rindex("}") + 1]) if isinstance(obj, dict): said = str(obj.get("reading", "")).strip().upper() return said if said in READINGS else "" except Exception: pass said = text.upper() for candidate in READINGS: if said == candidate: return candidate return "" def _why(raw: str) -> str: try: text = str(raw).strip() obj = json.loads(text[text.index("{"):text.rindex("}") + 1]) if isinstance(obj, dict): return _clip(str(obj.get("why", "")), MAX_WHY) except Exception: pass return _clip(str(raw), MAX_WHY) def _task(condition: str, url: str, page: str, facts: str) -> str: """Built from locals only. Nothing here may touch `self`.""" evidence = ("THE PAGE THE RULE NAMED AS THE PLACE TO CHECK, " + url + ", fetched just now:\n" + page) if url else ( "This rule names no page. It turns on what the token can see about " "itself, which is below.") return f"""A token was launched carrying a rule its creator wrote and can no longer change. Somebody is asking whether that rule's condition has been met. Decide one thing only. THE CONDITION, exactly as it was written into the token at launch: {condition} {evidence} WHAT THE TOKEN KNOWS ABOUT ITSELF RIGHT NOW, read from its own state: {facts} Answer {MET} if the condition has happened. You are being asked about **now**, not about whether it is likely to happen or nearly has. Answer {NOT_MET} if it has not happened yet. A condition that is close is not met. A condition that was met in the past and has since reversed is not met now. Answer {CANNOT_TELL} if what you have been given cannot settle it: the page is an error, a login wall, or does not speak to the condition at all, or the condition asks about something none of the material above covers. This is not a judgement of whether the rule is a good rule, or whether firing it now would be fair to anybody. The creator wrote it, everyone who bought could read it, and it means what it says. Reply with bare JSON and nothing else: {{"reading": "{MET}" or "{NOT_MET}" or "{CANNOT_TELL}", "why": "one sentence naming what decided it"}}""" class Token(gl.Contract): name: str symbol: str creator: str launched_at: str supply: u256 balances: TreeMap[str, u256] holders: DynArray[str] # Held by the token itself. Rules act on this rather than on anybody's # balance, so a rule can never reach into a holder's pocket. treasury: u256 # Written once, in __init__, and never touched again by any method here. rules: DynArray[str] # Append only. What actually happened, with the reasoning the validators # gave, so a reader can check the badge against the record. firings: DynArray[str] def __init__(self, name: str, symbol: str, supply: str, treasury_share: str, rules_json: str, creator: str) -> None: self.name = _clip(str(name), 60) self.symbol = _clip(str(symbol), 12).upper() # Passed in rather than taken from the sender, because a launchpad # deploying this on somebody's behalf is the sender and the person who # launched it is not. The creator has no powers here at all: they cannot # edit a rule, cannot stop a tick, and cannot take anything back. The # field says who launched it and nothing follows from it, so there is # nothing to gain by putting somebody else's address in. self.creator = _address(creator) or _addr(gl.message.sender_address.as_hex) self.launched_at = _now_iso() total = _whole(supply) if total <= 0: total = 1000000 share = _whole(treasury_share) if share < 0 or share > 100: share = 0 held = total * share // 100 self.supply = u256(total) self.treasury = u256(held) self.balances[self.creator] = u256(total - held) self.holders.append(self.creator) # Rules are validated here and then never written again. Anything # malformed is dropped at launch rather than kept as a rule that can # never fire, because a badge for a rule that cannot work is worse than # no badge. try: proposed = json.loads(str(rules_json)) except Exception: proposed = [] if not isinstance(proposed, list): proposed = [] for raw in proposed[:MAX_RULES]: if not isinstance(raw, dict): continue condition = " ".join(str(raw.get("when", "")).split()) action = str(raw.get("then", "")).strip().upper() amount = _whole(raw.get("amount", 0)) if len(condition) < MIN_CONDITION or len(condition) > MAX_CONDITION: continue if action not in ACTIONS: continue if amount <= 0 or amount > held: continue self.rules.append(json.dumps({ "index": len(self.rules), "when": condition, "url": _url(raw.get("url", "")), "then": action, "amount": amount, "state": WAITING, })) # ------------------------------------------------------------- the ledger @gl.public.view def balance_of(self, who: str) -> str: address = _address(who) return str(int(self.balances[address]) if address in self.balances else 0) @gl.public.write def transfer(self, to: str, amount: str) -> str: """An ordinary transfer. No round, no delay, nothing to ask anybody. Holders are not the risk here and are not made to wait for one. """ sender = _addr(gl.message.sender_address.as_hex) recipient = _address(to) wanted = _whole(amount) held = int(self.balances[sender]) if sender in self.balances else 0 if not recipient: return json.dumps({"ok": False, "error": "give an address to send to"}) if wanted <= 0 or wanted > held: return json.dumps({"ok": False, "held": str(held), "error": "not that much to send"}) self.balances[sender] = u256(held - wanted) if recipient not in self.balances: self.holders.append(recipient) self.balances[recipient] = u256(0) self.balances[recipient] = u256(int(self.balances[recipient]) + wanted) return json.dumps({"ok": True, "from": sender, "to": recipient, "amount": str(wanted)}) # -------------------------------------------------------------- the rules @gl.public.write def tick(self, rule: str) -> str: """Ask whether one rule's condition has been met, and act if it has. Open to everybody, and it has to be: a rule only the creator could trigger is a rule the creator would simply never trigger. Whoever makes a rule fire is paid for it out of the treasury. """ position = self._rule_index(rule) if position is None: return json.dumps({"ok": False, "error": "no rule at that index"}) record = json.loads(self.rules[position]) if record["state"] != WAITING: return json.dumps({"ok": False, "rule": position, "state": record["state"], "error": "that rule has already fired"}) caller = _addr(gl.message.sender_address.as_hex) # Read out here, where storage may be read, and pass them in as locals. condition = str(record["when"]) where = str(record["url"]) facts = self._facts() def look() -> str: # Locals only. Nothing here reads self and nothing here raises: # either would end the transaction rather than the round. page = "" if where: try: page = _clip(str(gl.nondet.web.render(where, mode="text")), MAX_PAGE) except Exception: page = "" if not page: return json.dumps({"reading": CANNOT_TELL, "why": "the page could not be retrieved"}) try: return str(gl.nondet.exec_prompt(_task(condition, where, page, facts))) except Exception: return "" raw = gl.eq_principle.prompt_comparative( look, principle=( f"Both answers must carry the same value in the field named reading, one of " f"{MET}, {NOT_MET} or {CANNOT_TELL}. That single field decides whether tokens " "are burned or paid out, so two readers differing on it are not wording a " "judgement differently, they are disagreeing about whether the thing has " "happened. The accompanying sentence is not compared, and where a page was " "fetched the two readers will not have identical copies of it." ), ) reading = _reading(raw) if not reading: return json.dumps({"ok": False, "rule": position, "state": WAITING, "error": "the round produced no reading this contract " "recognises"}) if reading != MET: return json.dumps({"ok": True, "rule": position, "reading": reading, "state": WAITING, "why": _why(raw), "moved": "0"}) # Met. From here it is arithmetic, and the creator has no say in it. amount = min(int(record["amount"]), int(self.treasury)) reward = amount * CALLER_SHARE // 10000 moved = amount - reward self.treasury = u256(int(self.treasury) - amount) if record["then"] == BURN: self.supply = u256(int(self.supply) - moved) else: self._distribute(moved) if reward > 0: self._credit(caller, reward) record["state"] = FIRED record["fired_at"] = _now_iso() record["fired_by"] = caller record["why"] = _why(raw) self.rules[position] = json.dumps(record) self.firings.append(json.dumps({ "rule": position, "when": record["when"], "then": record["then"], "amount": str(moved), "at": record["fired_at"], "by": caller, "why": record["why"], })) return json.dumps({"ok": True, "rule": position, "reading": MET, "state": FIRED, "action": record["then"], "moved": str(moved), "paid_caller": str(reward), "why": record["why"]}) def _distribute(self, amount: int) -> None: """Pay out pro rata to everybody holding a balance. The remainder of the division stays in the treasury rather than going to whoever happens to be first in the list. """ total = 0 for who in self.holders: total += int(self.balances[who]) if who in self.balances else 0 if total <= 0 or amount <= 0: self.treasury = u256(int(self.treasury) + amount) return paid = 0 for who in self.holders: held = int(self.balances[who]) if who in self.balances else 0 share = amount * held // total if share > 0: self.balances[who] = u256(held + share) paid += share if amount - paid > 0: self.treasury = u256(int(self.treasury) + (amount - paid)) def _credit(self, who: str, amount: int) -> None: if who not in self.balances: self.holders.append(who) self.balances[who] = u256(0) self.balances[who] = u256(int(self.balances[who]) + amount) def _facts(self) -> str: """What the token can say about itself, for a condition that turns on it.""" return json.dumps({ "name": self.name, "symbol": self.symbol, "supply": str(self.supply), "treasury": str(self.treasury), "holders": len(self.holders), "creator": self.creator, "creator_holds": str(int(self.balances[self.creator]) if self.creator in self.balances else 0), "launched_at": self.launched_at, "now": _now_iso(), }) # ------------------------------------------------------------- the badges @gl.public.view def rules_view(self) -> str: """Everything a buyer needs to judge the badge, and nothing softer. Not the creator's description of the rules: the rules themselves, frozen since launch, each with whether it has fired, when, who made it fire and what the validators said. A badge that showed only the claim would be the pinned message again with better styling. """ out = [] for position in range(len(self.rules)): record = json.loads(self.rules[position]) out.append({ "index": record["index"], "when": record["when"], "checked_against": record["url"] or None, "then": record["then"], "amount": str(record["amount"]), "state": record["state"], "fired_at": record.get("fired_at"), "fired_by": record.get("fired_by"), "why": record.get("why"), }) return json.dumps({ "token": self.symbol, "rules": out, "frozen": True, "note": ("these rules were written into the token when it was launched and " "no method on this contract can add, edit or remove one; anybody may " "call tick to make a rule whose condition is met carry itself out"), }) @gl.public.view def status(self) -> str: holders = [] for position in range(min(len(self.holders), MAX_HOLDERS_IN_REPORT)): who = self.holders[position] holders.append({"who": who, "holds": str(int(self.balances[who]) if who in self.balances else 0)}) return json.dumps({ "name": self.name, "symbol": self.symbol, "creator": self.creator, "launched_at": self.launched_at, "supply": str(self.supply), "treasury": str(self.treasury), "holders": len(self.holders), "top_holders": holders, "rules": len(self.rules), "fired": len([1 for p in range(len(self.rules)) if json.loads(self.rules[p])["state"] == FIRED]), }) @gl.public.view def firings_view(self) -> str: out = [json.loads(self.firings[p]) for p in range(len(self.firings))] return json.dumps({"token": self.symbol, "count": len(out), "firings": out}) # ---------------------------------------------------------------- internal def _rule_index(self, value: str) -> typing.Optional[int]: try: position = int(str(value).strip()) except Exception: return None if position < 0 or position >= len(self.rules): return None return position