Merge branch 'main' of github-study:one-zero-eight/hackathon-random-numbers

Author: SergePolin

backend/contract.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+import argparse
+import base64
+import json
+import os
+
+import requests
+import rfc8785
+from dotenv import load_dotenv
+from web3 import Web3
+
+ABI = [
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "internalType": "bytes32", "name": "payloadHash", "type": "bytes32"},
+            {"indexed": False, "internalType": "string", "name": "cid", "type": "string"},
+            {"indexed": False, "internalType": "string", "name": "kid", "type": "string"},
+            {"indexed": True, "internalType": "address", "name": "sender", "type": "address"},
+            {"indexed": False, "internalType": "uint256", "name": "ts", "type": "uint256"},
+        ],
+        "name": "GenerationPublished",
+        "type": "event",
+    },
+    {
+        "inputs": [
+            {"internalType": "bytes32", "name": "h", "type": "bytes32"},
+            {"internalType": "string", "name": "cid", "type": "string"},
+            {"internalType": "string", "name": "kid", "type": "string"},
+        ],
+        "name": "publish",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"internalType": "bytes32", "name": "", "type": "bytes32"}],
+        "name": "records",
+        "outputs": [
+            {"internalType": "bytes32", "name": "payloadHash", "type": "bytes32"},
+            {"internalType": "string", "name": "cid", "type": "string"},
+            {"internalType": "string", "name": "kid", "type": "string"},
+            {"internalType": "uint256", "name": "ts", "type": "uint256"},
+            {"internalType": "address", "name": "sender", "type": "address"},
+        ],
+        "stateMutability": "view",
+        "type": "function",
+    },
+    {
+        "inputs": [{"internalType": "bytes32", "name": "h", "type": "bytes32"}],
+        "name": "exists",
+        "outputs": [{"internalType": "bool", "name": "", "type": "bool"}],
+        "stateMutability": "view",
+        "type": "function",
+    },
+]
+
+
+def b64u_dec(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def pin_to_pinata(jwt: str, record: dict) -> str:
+    r = requests.post(
+        "https://api.pinata.cloud/pinning/pinJSONToIPFS",
+        headers={"Authorization": f"Bearer {jwt}", "Content-Type": "application/json"},
+        data=json.dumps(record, ensure_ascii=False, separators=(",", ":")).encode(),
+        timeout=60,
+    )
+    r.raise_for_status()
+    return r.json()["IpfsHash"]  # CID
+
+
+def publish_to_chain(
+    rpc_url: str, registry_addr: str, chain_id: int, private_key: str, h_bytes32: bytes, cid: str, kid: str
+) -> str | None:
+    w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 60}))
+    c = w3.eth.contract(address=Web3.to_checksum_address(registry_addr), abi=ABI)
+
+    if c.functions.exists(h_bytes32).call():
+        return None
+
+    acct = w3.eth.account.from_key(private_key)
+    tx = c.functions.publish(h_bytes32, cid, kid).build_transaction(
+        {
+            "from": acct.address,
+            "nonce": w3.eth.get_transaction_count(acct.address),
+            "chainId": chain_id,
+        }
+    )
+    signed = acct.sign_transaction(tx)
+    return w3.eth.send_raw_transaction(signed.raw_transaction).hex()
+
+
+def main():
+    load_dotenv()
+    ap = argparse.ArgumentParser(description="Pin RNG record to IPFS (Pinata) and publish to RNGRegistry")
+    ap.add_argument("--footprint", required=True, help="full ed25519.<kid>.<b64u(payload)>.{sig}")
+    ap.add_argument("--result", help="optional JSON string for 'result', e.g. '[85]'", default=None)
+    args = ap.parse_args()
+
+    # Parse footprint -> payload, kid, sig
+    alg, kid, p64, s64 = args.footprint.split(".", 3)
+    assert alg.lower() == "ed25519", "only Ed25519 supported"
+    payload = json.loads(b64u_dec(p64))
+    payload_dumped = rfc8785.dumps(payload)  # canonical
+    h_bytes32 = Web3.keccak(payload_dumped)  # bytes32
+    h_hex = h_bytes32.hex()
+
+    # Build record for IPFS
+    record = {
+        "schema": "gen.v1",
+        "footprint": args.footprint,
+        "payload": json.loads(payload_dumped),  # canonical object
+        "sig_alg": "Ed25519",
+        "kid": kid,
+        "sig_b64u": s64,
+    }
+    if args.result:
+        record["result"] = json.loads(args.result)
+
+    # Pinata
+    pinata_jwt = os.environ["PINATA_JWT"]
+    cid = pin_to_pinata(pinata_jwt, record)
+
+    # Publish on-chain
+    rpc = os.environ["RPC_URL"]
+    addr = os.environ["REGISTRY_ADDR"]
+    chain = int(os.getenv("CHAIN_ID", "84532"))
+    pk = os.environ["PRIVATE_KEY"]
+    tx_hash = publish_to_chain(rpc, addr, chain, pk, h_bytes32, cid, kid)
+
+    explorer = "https://sepolia.basescan.org" if chain == 84532 else "https://basescan.org"
+
+    print("payloadHash:", h_hex)
+    print("cid:", cid)
+    print("kid:", kid)
+
+    if tx_hash:
+        print("tx:", tx_hash)
+        print("tx_url:", f"{explorer}/tx/0x{tx_hash}#eventlog")
+    else:
+        print("Record already exists on-chain (skipped)")
+
+    print("gateway_url:", f"https://ipfs.io/ipfs/{cid}")
+    print("contract_url:", f"{explorer}/address/{addr}")
+    print("events_url:", f"{explorer}/address/{addr}#events")
+
+
+if __name__ == "__main__":
+    main()

backend/contract.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/// @title RNGRegistry — on-chain index of off-chain signed RNG payloads
+/// @notice Store keccak256(payload_dumped) + CID + KID with a timestamp. Ed25519 is verified off-chain.
+contract RNGRegistry {
+    struct Record {
+        bytes32 payloadHash; // keccak256(payload_dumped)
+        string  cid;         // ipfs://CID or ar://TXID (store raw id, not the scheme)
+        string  kid;         // key identifier for Ed25519 public key lookup
+        uint256 ts;          // block.timestamp of publication
+        address sender;      // msg.sender who published
+    }
+
+    /// @dev Emitted on each successful publish
+    event GenerationPublished(
+        bytes32 indexed payloadHash,
+        string cid,
+        string kid,
+        address indexed sender,
+        uint256 ts
+    );
+
+    /// @notice Optional storage mirror for easy RPC reads; key = payloadHash
+    mapping(bytes32 => Record) public records;
+
+    /// @notice Publish a single RNG record
+    /// @param h   keccak256(payload_dumped) as bytes32
+    /// @param cid IPFS CID (or Arweave TXID) as string
+    /// @param kid Key ID to resolve Ed25519 public key off-chain
+    function publish(bytes32 h, string calldata cid, string calldata kid) external {
+        require(records[h].ts == 0, "exists");
+        records[h] = Record({
+            payloadHash: h,
+            cid: cid,
+            kid: kid,
+            ts: block.timestamp,
+            sender: msg.sender
+        });
+        emit GenerationPublished(h, cid, kid, msg.sender, block.timestamp);
+    }
+
+    /// @notice Publish multiple RNG records in one transaction
+    function publishBatch(
+        bytes32[] calldata hashes,
+        string[]  calldata cids,
+        string[]  calldata kids
+    ) external {
+        uint256 n = hashes.length;
+        require(cids.length == n && kids.length == n, "len mismatch");
+        for (uint256 i = 0; i < n; i++) {
+            bytes32 h = hashes[i];
+            require(records[h].ts == 0, "exists");
+            records[h] = Record({
+                payloadHash: h,
+                cid: cids[i],
+                kid: kids[i],
+                ts: block.timestamp,
+                sender: msg.sender
+            });
+            emit GenerationPublished(h, cids[i], kids[i], msg.sender, block.timestamp);
+        }
+    }
+
+    /// @notice Check existence without reading the full struct
+    function exists(bytes32 h) external view returns (bool) {
+        return records[h].ts != 0;
+    }
+}

backend/pyproject.toml

@@ -35,6 +35,7 @@ dependencies = [
     "rfc8785>=0.1.4",
     "av>=16.0.1",
     "pillow>=12.0.0",
+    "web3>=7.14.0",
 ]
 
 [dependency-groups]

backend/settings.example.yaml

@@ -16,3 +16,9 @@ signature_secret_key: |
   -----END OPENSSH PRIVATE KEY-----
 signature_public_key: |
   ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX key-2025-10
+# Blockchain and IPFS settings (optional, for publishing to smart contract)
+pinata_jwt: null # JWT token for Pinata IPFS service,
+rpc_url: https://sepolia.base.org # Blockchain RPC URL (e.g., Base Sepolia Testnet - https://sepolia.base.org)
+registry_address: "0xaEa80F09eF923257c97E5cbDF97b42075D7D7bbB" # RNGRegistry smart contract address
+chain_id: 84532 # Base Sepolia Testnet
+blockchain_private_key: null # Private key for blockchain transactions

backend/settings.schema.yaml

@@ -70,7 +70,7 @@ properties:
     type: string
     writeOnly: true
   signature_public_key:
-    description: Public key for verifying API responses, use `` to generate
+    description: Public key for verifying API responses
     format: password
     title: Signature Public Key
     type: string
@@ -80,6 +80,54 @@ properties:
     description: Key ID for signing API responses
     title: Signature Kid
     type: string
+  pinata_jwt:
+    anyOf:
+    - format: password
+      type: string
+      writeOnly: true
+    - type: 'null'
+    default: null
+    description: JWT token for Pinata IPFS service
+    title: Pinata Jwt
+  rpc_url:
+    anyOf:
+    - type: string
+    - type: 'null'
+    default: null
+    description: Blockchain RPC URL (e.g., Base Sepolia)
+    examples:
+    - https://sepolia.base.org
+    - https://base.org
+    title: Rpc Url
+  registry_address:
+    anyOf:
+    - type: string
+    - type: 'null'
+    default: null
+    description: RNGRegistry smart contract address
+    examples:
+    - '0x0000000000000000000000000000000000000000'
+    title: Registry Address
+  chain_id:
+    default: 84532
+    description: Blockchain chain ID (84532 for Base Sepolia Testnet, 8453 for Base
+      Mainnet)
+    examples:
+    - 84532
+    - 8453
+    title: Chain Id
+    type: integer
+  blockchain_private_key:
+    anyOf:
+    - format: password
+      type: string
+      writeOnly: true
+    - type: 'null'
+    default: null
+    description: Private key for blockchain transactions
+    examples:
+    - badsaubtdsaubt
+    title: Blockchain Private Key
 required:
 - session_secret_key
 - entropy_secret_key

backend/src/config_schema.py

@@ -16,7 +16,7 @@ class SettingBaseModel(BaseModel):
 
 class Settings(SettingBaseModel):
     """Settings for the application."""
-    
+
     schema_: str | None = Field(None, alias="$schema")
     environment: Environment = Environment.DEVELOPMENT
     "App environment flag"
@@ -47,6 +47,16 @@ class Settings(SettingBaseModel):
     "Public key for verifying API responses"
     signature_kid: str = "key-2025-10"
     "Key ID for signing API responses"
+    pinata_jwt: SecretStr | None = None
+    "JWT token for Pinata IPFS service"
+    rpc_url: str | None = Field(None, examples=["https://sepolia.base.org", "https://base.org"])
+    "Blockchain RPC URL (e.g., Base Sepolia)"
+    registry_address: str | None = Field(None, examples=["0x0000000000000000000000000000000000000000"])
+    "RNGRegistry smart contract address"
+    chain_id: int = Field(84532, examples=[84532, 8453])
+    "Blockchain chain ID (84532 for Base Sepolia Testnet, 8453 for Base Mainnet)"
+    blockchain_private_key: SecretStr | None = Field(None, examples=["badsaubtdsaubt"])
+    "Private key for blockchain transactions"
 
     @classmethod
     def from_yaml(cls, path: Path) -> "Settings":

backend/src/modules/blockchain/__init__.py

@@ -0,0 +1,18 @@
+from pydantic import BaseModel
+
+
+class Web3PublishResult(BaseModel):
+    payload_hash: str
+    "Keccak256 hash of the canonical payload"
+    cid: str
+    "IPFS CID where the record is pinned"
+    kid: str
+    "Key ID used for signing"
+    tx_hash: str | None = None
+    "Transaction hash if published to blockchain (None if already exists)"
+    gateway_url: str
+    "IPFS gateway URL to access the record"
+    tx_url: str | None = None
+    "Blockchain explorer transaction URL"
+    contract_url: str
+    "Blockchain explorer contract URL"