简介这是一份面向Python开发者与区块链初学者的实战项目源码围绕「区块链上的时间胶囊」展开帮助读者理解如何用Python与智能合约实现信息的定时加密存储与不可篡改记录。资源包共24个文件约159KB以JavaScript、Vue组件、Solidity合约及JSON配置为主涵盖前端界面、合约部署脚本与项目配置目录结构清晰便于按模块阅读。项目核心包括区块链连接、时间戳创建、数据加密、智能合约解锁规则、命令行或Web接口设计以及本地元数据持久化等环节读者可借此掌握web3.py、pyethereum等库的调用方式并熟悉加密算法与合约编写流程。目前已有203人学习下载适合希望从零搭建去中心化时间胶囊系统、提升分布式系统与信息安全实践能力的中级开发者参考。1. 用 Python 在区块链上写一枚时间胶囊它到底锁住了什么把一段话、一张图、一份 PDF 的哈希写进区块链设定一个未来才允许读取的时间点到期前谁也打不开——这就是「Python-区块链上的时间胶囊」在工程上真正要做的事。它解决的不是「存文件」,而是「证明某份内容在某个时刻之前就已经存在且之后没被改过」。很多人第一次听到会以为要把文件本体塞进链上其实链上只放哈希和加密后的密钥分片文件本体留在本地或对象存储里。适合谁做会一点 Python 基础语法、想找一个能跑通「加密 链上写入 定时解锁」全链路的练手项目的人也适合需要给合同、设计稿、遗嘱类数字资产做时间锚定的开发者。下面按「先立住原理再动手复现最后讲坑」的顺序拆开。2. 时间胶囊的密码学骨架哈希、对称加密与时间锁怎么拼2.1 为什么链上只放哈希不放原文区块链的存储是按字节收费的把一张 2MB 的图片直接写进链上手续费会高到让你怀疑人生而且全节点都要同步这份数据属于典型的资源滥用。常见做法是文件本体用 AES 对称加密密文留在本地磁盘或对象存储链上只写三样东西——密文的 SHA-256 哈希、加密用的算法标识、以及解锁时间戳。哈希的作用是防篡改任何人拿到密文后重新算一遍哈希和链上记录比对不一致就说明文件被动过。这里有个容易翻车的点哈希要算在密文上而不是明文上否则等于把原文指纹公开了别人拿字典一撞就能猜出你锁了什么。2.2 时间锁的两种实现路线时间锁timelock决定「到期前打不开」这件事靠什么保证。第一种是链上合约锁把解密密钥用合约的require(block.timestamp unlockTime)守住到期后调用合约才返回密钥。第二种是本地时间锁密钥用一层基于时间的派生函数加密到期前算不出正确密钥。前者依赖链的出块时间后者依赖本地时钟。我一般推荐合约锁因为链上时间戳是全网共识的本地时钟用户可以自己改安全性差一截。下面这段是合约锁的核心逻辑用 Solidity 写Python 侧通过 web3.py 调用// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract TimeCapsule { address public owner; uint256 public unlockTime; bytes32 public contentHash; // 密文的 SHA-256 string private secretKey; // 到期后才返回的密钥 constructor(bytes32 _hash, uint256 _unlockTime, string memory _key) { owner msg.sender; contentHash _hash; unlockTime _unlockTime; secretKey _key; } // 到期前调用直接 revert这是时间锁的关键 function reveal() public view returns (string memory) { require(block.timestamp unlockTime, capsule is still locked); return secretKey; } }逻辑说明unlockTime存的是 Unix 时间戳reveal()里的require是唯一的门禁链上时间没到就抛异常。参数上要注意block.timestamp是秒级Python 侧生成时间戳时别用毫秒否则会差 1000 倍胶囊会被锁到几万年以后。secretKey用private只是语法层面不可直接读链上数据本质是公开的所以密钥本身必须再经过一层加密不能明文写进合约——这一点后面避坑章节会展开。2.3 Python 侧的最小依赖清单跑通整条链路只需要四个库web3负责和链交互cryptography负责 AES 加密hashlib是标准库算哈希eth-account用来签名交易。安装命令如下建议在虚拟环境里做避免污染系统 Pythonpython -m venv capsule-env source capsule-env/bin/activate # Windows 用 capsule-env\Scripts\activate pip install web3 cryptography eth-account参数说明web3版本建议 6.x 以上5.x 的 API 差异较大很多网上的老代码直接抄会报AttributeError。cryptography装完自带 OpenSSL 绑定AES-GCM 模式开箱即用。如果你用的是 VSCode 配置 Python 环境记得把解释器切到capsule-env里的那个否则 pip 装到了全局运行时又找不到模块这是新手最常见的环境翻车。3. 从零跑通一枚胶囊加密、上链、到期解锁的完整代码3.1 生成密钥并加密你的内容先解决「锁什么、用什么锁」。下面这段把一段文字加密成密文同时算出密文哈希这两个产物一个留本地、一个上链import hashlib from cryptography.hazmat.primitives.ciphers.aead import AESGCM import os def encrypt_content(plaintext: str): # 生成 256 位随机密钥和 96 位 noncenonce 绝不能复用 key AESGCM.generate_key(bit_length256) nonce os.urandom(12) aes AESGCM(key) ciphertext aes.encrypt(nonce, plaintext.encode(utf-8), None) # 哈希算在密文上不是明文 content_hash hashlib.sha256(ciphertext).hexdigest() return key, nonce, ciphertext, content_hash key, nonce, ciphertext, content_hash encrypt_content(这是我 2025 年写给三年后自己的话) print(密文哈希:, content_hash)逻辑说明AES-GCM 是带认证的加密模式解密时如果密文被改过会直接抛InvalidTag比 CBC 模式多一层完整性保护。参数上nonce必须是 12 字节且每次加密都换新的同一个 key 下 nonce 重复会导致密钥流复用安全性直接归零这是血泪经验。content_hash是十六进制字符串长度 64上链前要转成bytes32。3.2 把哈希和加密后的密钥写进合约密钥不能明文上链常见做法是用一个只有到期后才公开的口令再包一层或者干脆把密钥拆成两半一半上链一半本地存。这里演示最简版本把密钥用口令派生出的密钥加密后再上链from web3 import Web3 from eth_account import Account import hashlib, os w3 Web3(Web3.HTTPProvider(http://127.0.0.1:8545)) # 本地节点 acct Account.from_key(os.environ[PRIVATE_KEY]) # 用口令派生密钥把 AES key 再加密一层 from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC from cryptography.hazmat.primitives import hashes def wrap_key(aes_key: bytes, passphrase: str, salt: bytes): kdf PBKDF2HMAC(algorithmhashes.SHA256(), length32, saltsalt, iterations200_000) wrapping kdf.derive(passphrase.encode()) return AESGCM(wrapping).encrypt(os.urandom(12), aes_key, None) wrapped wrap_key(key, my-secret-passphrase, os.urandom(16)) print(上链的密钥密文长度:, len(wrapped))逻辑说明PBKDF2 的iterations设 20 万次是当前比较稳妥的下限太低会被暴力破解太高会让解锁时卡顿。salt要随机且和密文一起保存否则同样的口令每次派生出一样的密钥容易被彩虹表命中。wrapped才是真正写进合约secretKey字段的内容即使链上数据公开没有口令也解不开。3.3 部署合约并验证解锁时间部署和调用用 web3.py 完成关键是构造交易时把content_hash转成bytes32把解锁时间转成整数秒import time, json unlock_ts int(time.time()) 3 * 24 * 3600 # 三天后解锁 hash_bytes bytes.fromhex(content_hash) # 假设已编译好合约拿到 abi 和 bytecode contract w3.eth.contract(abiabi, bytecodebytecode) tx contract.constructor(hash_bytes, unlock_ts, wrapped.hex()).build_transaction({ from: acct.address, nonce: w3.eth.get_transaction_count(acct.address), gas: 3_000_000, gasPrice: w3.eth.gas_price, }) signed acct.sign_transaction(tx) tx_hash w3.eth.send_raw_transaction(signed.rawTransaction) receipt w3.eth.wait_for_transaction_receipt(tx_hash) print(合约地址:, receipt.contractAddress)逻辑说明unlock_ts用int(time.time())拿秒级时间戳加三天秒数。gas给 300 万是留足余量实际部署大概消耗 40 万左右给太少会out of gas导致部署失败但手续费照扣。wrapped.hex()把字节转成十六进制字符串因为合约里secretKey是string类型。部署完记下contractAddress这是后续解锁的唯一入口。3.4 到期后取回密钥并解密解锁时先调reveal()拿回密钥密文再用口令解出 AES key最后解密密文capsule w3.eth.contract(addressreceipt.contractAddress, abiabi) try: wrapped_hex capsule.functions.reveal().call() print(解锁成功密钥密文:, wrapped_hex[:32], ...) except Exception as e: print(还没到期或调用失败:, e)逻辑说明reveal()是view函数调用不消耗 gas但时间没到会 revertweb3.py 会抛异常所以要用 try 包住。拿到wrapped_hex后用之前的口令和 salt 走一遍 PBKDF2 派生再 AES-GCM 解密就得到原始 AES key最后解密密文还原内容。整条链路里口令是唯一需要你自己记住的东西丢了就真打不开了没有后悔药。4. 避坑与排查时间胶囊最容易翻车的五个地方4.1 时间戳单位搞错胶囊被锁到几万年后现象部署完发现reveal()一直 revert明明设的是「三天后」。原因Python 的time.time()返回秒但有些前端库或Date.now()返回毫秒混用后unlockTime变成 1.7 万亿级别对应公元五万多年。解决统一用秒部署前打印unlock_ts和int(time.time())对比差值应该就是你要的天数乘以 86400。4.2 nonce 复用导致密文可被破解现象同一批胶囊用同一个 AES key 加密多条内容安全审计时被判高危。原因AES-GCM 在同一个 key 下复用 nonce攻击者拿到两条密文异或就能还原明文。解决每次加密都os.urandom(12)生成新 nonce并把 nonce 和密文一起保存解密时按顺序取。4.3 把明文哈希写上了链现象以为很安全结果别人拿常见词字典一撞就猜出你锁的是「生日快乐」。原因哈希算在了明文上短文本的哈希空间太小字典攻击成本极低。解决哈希一律算在密文上密文本身有随机 nonce同样的明文每次密文都不同撞不出来。4.4 私钥硬编码进脚本现象代码传到公开仓库几分钟后钱包被清空。原因PRIVATE_KEY直接写在.py里。解决用环境变量或.env文件加载.env加进.gitignore。测试网私钥也别大意养成习惯比事后补救强。4.5 本地节点没同步完就发交易现象send_raw_transaction报nonce too low或交易一直 pending。原因本地节点还在同步get_transaction_count拿到的是旧值。解决部署前用w3.eth.block_number确认节点已跟上最新区块或者直接用托管节点服务省去同步等待。5. 进阶把胶囊做成可验证、可批量、可迁移的形态跑通单枚胶囊之后真正值得投入的是把它工程化。第一件事是加验证接口除了reveal()再写一个verify(bytes32 candidate)函数任何人拿密文算哈希后调它返回 true/false这样不用解锁也能证明「这份文件就是当初锁进去的那份」。第二件事是批量管理用一个mapping(uint256 Capsule)存多枚胶囊配合 Python 侧读事件日志CapsuleCreated来索引避免手动记地址。第三件事是迁移链上合约一旦部署就改不了所以解锁逻辑要留升级空间常见做法是代理合约模式把数据层和逻辑层分开。验证方法上我习惯写一个端到端测试脚本加密 → 部署 → 模拟时间前进本地节点用evm_increaseTime→ 调reveal()→ 解密 → 比对原文。本地 Hardhat 或 Anvil 节点都支持时间跳跃不用真等三天。参数上evm_increaseTime传秒数跳完记得evm_mine出一个新块否则block.timestamp不会更新这是很多人调半天没反应的原因。最后说个习惯每次改完合约先在测试网跑一遍完整流程再上主网gas 费和不可逆性决定了链上没有后悔药。我自己就吃过没测就部署的亏一笔交易发出去合约逻辑写错也只能重新部署旧地址永远留在链上。把测试脚本当成项目的一部分维护比事后补救省心得多。希望帮到你。本文还有配套的精品资源点击获取 Python区块链时间胶囊：加密、上链与定时解锁实战
简介这是一份面向Python开发者与区块链初学者的实战项目源码围绕「区块链上的时间胶囊」展开帮助读者理解如何用Python与智能合约实现信息的定时加密存储与不可篡改记录。资源包共24个文件约159KB以JavaScript、Vue组件、Solidity合约及JSON配置为主涵盖前端界面、合约部署脚本与项目配置目录结构清晰便于按模块阅读。项目核心包括区块链连接、时间戳创建、数据加密、智能合约解锁规则、命令行或Web接口设计以及本地元数据持久化等环节读者可借此掌握web3.py、pyethereum等库的调用方式并熟悉加密算法与合约编写流程。目前已有203人学习下载适合希望从零搭建去中心化时间胶囊系统、提升分布式系统与信息安全实践能力的中级开发者参考。1. 用 Python 在区块链上写一枚时间胶囊它到底锁住了什么把一段话、一张图、一份 PDF 的哈希写进区块链设定一个未来才允许读取的时间点到期前谁也打不开——这就是「Python-区块链上的时间胶囊」在工程上真正要做的事。它解决的不是「存文件」,而是「证明某份内容在某个时刻之前就已经存在且之后没被改过」。很多人第一次听到会以为要把文件本体塞进链上其实链上只放哈希和加密后的密钥分片文件本体留在本地或对象存储里。适合谁做会一点 Python 基础语法、想找一个能跑通「加密 链上写入 定时解锁」全链路的练手项目的人也适合需要给合同、设计稿、遗嘱类数字资产做时间锚定的开发者。下面按「先立住原理再动手复现最后讲坑」的顺序拆开。2. 时间胶囊的密码学骨架哈希、对称加密与时间锁怎么拼2.1 为什么链上只放哈希不放原文区块链的存储是按字节收费的把一张 2MB 的图片直接写进链上手续费会高到让你怀疑人生而且全节点都要同步这份数据属于典型的资源滥用。常见做法是文件本体用 AES 对称加密密文留在本地磁盘或对象存储链上只写三样东西——密文的 SHA-256 哈希、加密用的算法标识、以及解锁时间戳。哈希的作用是防篡改任何人拿到密文后重新算一遍哈希和链上记录比对不一致就说明文件被动过。这里有个容易翻车的点哈希要算在密文上而不是明文上否则等于把原文指纹公开了别人拿字典一撞就能猜出你锁了什么。2.2 时间锁的两种实现路线时间锁timelock决定「到期前打不开」这件事靠什么保证。第一种是链上合约锁把解密密钥用合约的require(block.timestamp unlockTime)守住到期后调用合约才返回密钥。第二种是本地时间锁密钥用一层基于时间的派生函数加密到期前算不出正确密钥。前者依赖链的出块时间后者依赖本地时钟。我一般推荐合约锁因为链上时间戳是全网共识的本地时钟用户可以自己改安全性差一截。下面这段是合约锁的核心逻辑用 Solidity 写Python 侧通过 web3.py 调用// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract TimeCapsule { address public owner; uint256 public unlockTime; bytes32 public contentHash; // 密文的 SHA-256 string private secretKey; // 到期后才返回的密钥 constructor(bytes32 _hash, uint256 _unlockTime, string memory _key) { owner msg.sender; contentHash _hash; unlockTime _unlockTime; secretKey _key; } // 到期前调用直接 revert这是时间锁的关键 function reveal() public view returns (string memory) { require(block.timestamp unlockTime, capsule is still locked); return secretKey; } }逻辑说明unlockTime存的是 Unix 时间戳reveal()里的require是唯一的门禁链上时间没到就抛异常。参数上要注意block.timestamp是秒级Python 侧生成时间戳时别用毫秒否则会差 1000 倍胶囊会被锁到几万年以后。secretKey用private只是语法层面不可直接读链上数据本质是公开的所以密钥本身必须再经过一层加密不能明文写进合约——这一点后面避坑章节会展开。2.3 Python 侧的最小依赖清单跑通整条链路只需要四个库web3负责和链交互cryptography负责 AES 加密hashlib是标准库算哈希eth-account用来签名交易。安装命令如下建议在虚拟环境里做避免污染系统 Pythonpython -m venv capsule-env source capsule-env/bin/activate # Windows 用 capsule-env\Scripts\activate pip install web3 cryptography eth-account参数说明web3版本建议 6.x 以上5.x 的 API 差异较大很多网上的老代码直接抄会报AttributeError。cryptography装完自带 OpenSSL 绑定AES-GCM 模式开箱即用。如果你用的是 VSCode 配置 Python 环境记得把解释器切到capsule-env里的那个否则 pip 装到了全局运行时又找不到模块这是新手最常见的环境翻车。3. 从零跑通一枚胶囊加密、上链、到期解锁的完整代码3.1 生成密钥并加密你的内容先解决「锁什么、用什么锁」。下面这段把一段文字加密成密文同时算出密文哈希这两个产物一个留本地、一个上链import hashlib from cryptography.hazmat.primitives.ciphers.aead import AESGCM import os def encrypt_content(plaintext: str): # 生成 256 位随机密钥和 96 位 noncenonce 绝不能复用 key AESGCM.generate_key(bit_length256) nonce os.urandom(12) aes AESGCM(key) ciphertext aes.encrypt(nonce, plaintext.encode(utf-8), None) # 哈希算在密文上不是明文 content_hash hashlib.sha256(ciphertext).hexdigest() return key, nonce, ciphertext, content_hash key, nonce, ciphertext, content_hash encrypt_content(这是我 2025 年写给三年后自己的话) print(密文哈希:, content_hash)逻辑说明AES-GCM 是带认证的加密模式解密时如果密文被改过会直接抛InvalidTag比 CBC 模式多一层完整性保护。参数上nonce必须是 12 字节且每次加密都换新的同一个 key 下 nonce 重复会导致密钥流复用安全性直接归零这是血泪经验。content_hash是十六进制字符串长度 64上链前要转成bytes32。3.2 把哈希和加密后的密钥写进合约密钥不能明文上链常见做法是用一个只有到期后才公开的口令再包一层或者干脆把密钥拆成两半一半上链一半本地存。这里演示最简版本把密钥用口令派生出的密钥加密后再上链from web3 import Web3 from eth_account import Account import hashlib, os w3 Web3(Web3.HTTPProvider(http://127.0.0.1:8545)) # 本地节点 acct Account.from_key(os.environ[PRIVATE_KEY]) # 用口令派生密钥把 AES key 再加密一层 from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC from cryptography.hazmat.primitives import hashes def wrap_key(aes_key: bytes, passphrase: str, salt: bytes): kdf PBKDF2HMAC(algorithmhashes.SHA256(), length32, saltsalt, iterations200_000) wrapping kdf.derive(passphrase.encode()) return AESGCM(wrapping).encrypt(os.urandom(12), aes_key, None) wrapped wrap_key(key, my-secret-passphrase, os.urandom(16)) print(上链的密钥密文长度:, len(wrapped))逻辑说明PBKDF2 的iterations设 20 万次是当前比较稳妥的下限太低会被暴力破解太高会让解锁时卡顿。salt要随机且和密文一起保存否则同样的口令每次派生出一样的密钥容易被彩虹表命中。wrapped才是真正写进合约secretKey字段的内容即使链上数据公开没有口令也解不开。3.3 部署合约并验证解锁时间部署和调用用 web3.py 完成关键是构造交易时把content_hash转成bytes32把解锁时间转成整数秒import time, json unlock_ts int(time.time()) 3 * 24 * 3600 # 三天后解锁 hash_bytes bytes.fromhex(content_hash) # 假设已编译好合约拿到 abi 和 bytecode contract w3.eth.contract(abiabi, bytecodebytecode) tx contract.constructor(hash_bytes, unlock_ts, wrapped.hex()).build_transaction({ from: acct.address, nonce: w3.eth.get_transaction_count(acct.address), gas: 3_000_000, gasPrice: w3.eth.gas_price, }) signed acct.sign_transaction(tx) tx_hash w3.eth.send_raw_transaction(signed.rawTransaction) receipt w3.eth.wait_for_transaction_receipt(tx_hash) print(合约地址:, receipt.contractAddress)逻辑说明unlock_ts用int(time.time())拿秒级时间戳加三天秒数。gas给 300 万是留足余量实际部署大概消耗 40 万左右给太少会out of gas导致部署失败但手续费照扣。wrapped.hex()把字节转成十六进制字符串因为合约里secretKey是string类型。部署完记下contractAddress这是后续解锁的唯一入口。3.4 到期后取回密钥并解密解锁时先调reveal()拿回密钥密文再用口令解出 AES key最后解密密文capsule w3.eth.contract(addressreceipt.contractAddress, abiabi) try: wrapped_hex capsule.functions.reveal().call() print(解锁成功密钥密文:, wrapped_hex[:32], ...) except Exception as e: print(还没到期或调用失败:, e)逻辑说明reveal()是view函数调用不消耗 gas但时间没到会 revertweb3.py 会抛异常所以要用 try 包住。拿到wrapped_hex后用之前的口令和 salt 走一遍 PBKDF2 派生再 AES-GCM 解密就得到原始 AES key最后解密密文还原内容。整条链路里口令是唯一需要你自己记住的东西丢了就真打不开了没有后悔药。4. 避坑与排查时间胶囊最容易翻车的五个地方4.1 时间戳单位搞错胶囊被锁到几万年后现象部署完发现reveal()一直 revert明明设的是「三天后」。原因Python 的time.time()返回秒但有些前端库或Date.now()返回毫秒混用后unlockTime变成 1.7 万亿级别对应公元五万多年。解决统一用秒部署前打印unlock_ts和int(time.time())对比差值应该就是你要的天数乘以 86400。4.2 nonce 复用导致密文可被破解现象同一批胶囊用同一个 AES key 加密多条内容安全审计时被判高危。原因AES-GCM 在同一个 key 下复用 nonce攻击者拿到两条密文异或就能还原明文。解决每次加密都os.urandom(12)生成新 nonce并把 nonce 和密文一起保存解密时按顺序取。4.3 把明文哈希写上了链现象以为很安全结果别人拿常见词字典一撞就猜出你锁的是「生日快乐」。原因哈希算在了明文上短文本的哈希空间太小字典攻击成本极低。解决哈希一律算在密文上密文本身有随机 nonce同样的明文每次密文都不同撞不出来。4.4 私钥硬编码进脚本现象代码传到公开仓库几分钟后钱包被清空。原因PRIVATE_KEY直接写在.py里。解决用环境变量或.env文件加载.env加进.gitignore。测试网私钥也别大意养成习惯比事后补救强。4.5 本地节点没同步完就发交易现象send_raw_transaction报nonce too low或交易一直 pending。原因本地节点还在同步get_transaction_count拿到的是旧值。解决部署前用w3.eth.block_number确认节点已跟上最新区块或者直接用托管节点服务省去同步等待。5. 进阶把胶囊做成可验证、可批量、可迁移的形态跑通单枚胶囊之后真正值得投入的是把它工程化。第一件事是加验证接口除了reveal()再写一个verify(bytes32 candidate)函数任何人拿密文算哈希后调它返回 true/false这样不用解锁也能证明「这份文件就是当初锁进去的那份」。第二件事是批量管理用一个mapping(uint256 Capsule)存多枚胶囊配合 Python 侧读事件日志CapsuleCreated来索引避免手动记地址。第三件事是迁移链上合约一旦部署就改不了所以解锁逻辑要留升级空间常见做法是代理合约模式把数据层和逻辑层分开。验证方法上我习惯写一个端到端测试脚本加密 → 部署 → 模拟时间前进本地节点用evm_increaseTime→ 调reveal()→ 解密 → 比对原文。本地 Hardhat 或 Anvil 节点都支持时间跳跃不用真等三天。参数上evm_increaseTime传秒数跳完记得evm_mine出一个新块否则block.timestamp不会更新这是很多人调半天没反应的原因。最后说个习惯每次改完合约先在测试网跑一遍完整流程再上主网gas 费和不可逆性决定了链上没有后悔药。我自己就吃过没测就部署的亏一笔交易发出去合约逻辑写错也只能重新部署旧地址永远留在链上。把测试脚本当成项目的一部分维护比事后补救省心得多。希望帮到你。本文还有配套的精品资源点击获取