starcoin代码概要

Owned by YSG
Last updated: 2月 10, 2023
3 min read

1.按文件夹分类

abi

 

account

  • 理解account_storage对应有那几个column, 各个column的作用，account_storage和starcoin blockstorage 有哪些区别， 理解AccountInfo和Address关系

  • 查看AccountService和cmd/starcoin/src/account之间的交互

  • 理解dev, test网络为何可以直接从association_address 转账, 其他网络不行

 

block-replayer 待补充

 

 

chain

chain相关分成ChainReader和ChainWriter两个trait

ChainReader方面

  • 理解BlockChain如何通过BlockAccumulatorStorage根据BlockNumber获得对应的Block

  • 理解如何通过TransactionAccumulatorStorage根据transaction_global_index获得对应的Transaction

  • 理解Chain启动时候如何得到ChainInfo,这里StartupInfo的作用是什么

  • 理解Chain相关Epoch定义是什么，如何通过on_chain_config生成新的Epoch，什么是Uncle block

ChainWriter方面

  • 结合executor方面理解apply时候genesis block和非genesis block有什么区别

  • 理解apply时候四种不同的verify区别是什么

  • apply时候结合vm-runtime理解write_set的作用是什么

 

cmd

  • airdrop 空投程序

  • db-exporter db相关工具，提供block离线导入，导出，快照导入，导出(导出支持增量导出), 导出Resource, verify module错误, 理解快照导出为什么需要使用两次StateNode的数据

  • faucet 水龙头，供barnard使用

  • generator 生成genesis config和genesis，似乎被starcoin-genesis替代了

  • genesis-nft-miner 待补充

  • index block数据导入到elasticsearch的工具

  • merkle-generator 待补充

  • miner_client 挖矿客户端, CpuSolver如何使用多线程挖矿, 和BlockHeaderExtra之间联系 (俊哥补充)

  • peer-watcher 发现peer的小程序

  • replay 离线数据库拷贝其block到当前数据库下，目前主要被db-exporter的离线导入替代

  • resource-exporter 资源导入程序，移植到了db-exporter

  • starcoin

1.account console下account客户端命令同account文件夹服务器之间通过json rpc操作， account 相关逻辑入口， 主要分为账号操作，交易操作,多签相关命令

2.chain console下chain客户端命令，主要就是读取block和txn相关信息

3.dev 开发相关命令，其中compiler, deploy, package, move_explain移到了vm/move-package-manager, 执行合约和调用api命令, 升级module相关

4. node manager 执行block相关命令，删除区块，重新执行区块等, network 添加删除peer, peer 诊断相关命令, service 待补充， sync 查看同步状态，进度，取消同步等

5. state 获取账号下Module对应Code或Resource，获取Proof，显示账号下所有Code和Resource

  • tx-factory

main.rs是starcoin客户端入口函数，启动流程待补充

启动的Service有(待补充每个Service作用)

AccountService,

AccountEventService,

TxPoolService,

ChainReaderService,

ChainNotifyHandlerService,

BlockConnectorService,

SyncService,

BlockRelayer,

NetWorkRpcService,

TxSyncService,

CreateBlockTemplateService,

MinerService,

MetricsActorService,

PubSubService,

RpcService,

StratumService

 

commons

  • accumulator https://github.com/starcoinorg/starcoin-cookbook/blob/main/i18n/zh/docusaurus-plugin-content-docs/current/99-concepts/06-accumulator.md

    • 查看InMemoryAccumulator理解Accumulator在内存如何实现(有哪几种节点类型,如何更新root节点)，持久化到磁盘中如何使用rocksdb实现，参考BlockAccumulatorStorage和TransactionAccumulatorStorage, 相关的key, value是什么，结合test_block_chain_txn_info_fork_mapping是如何处理分叉的(理解pow和pos(aptos)在这点上不同)，如何做到幂等性, 这里

  • api-limiter 理解global_limiter和user_limiter是哪两个维度来限制调用

  • bcs_ext bcs序列化和反序列化封装

  • decrypt aes相关解密算法，account模块用到

  • forable-jellyfish-merkle https://github.com/starcoinorg/starcoin-cookbook/blob/main/i18n/zh/docusaurus-plugin-content-docs/current/99-concepts/05-smt.md

  • logger 理解info和debug日志之间区别(init()和init_for_test())，方便打印日志排查和阅读代码，或者使用IDE带的调试器，以及使用rust-gdb或者rust-lldb工具调试

  • metrics 性能统计图表用到

  • scmd 实现CommandAction trait， 供cmd下console命令行发送接口返回数据

  • serde-helps serde封装

  • service-registry actix封装提供各种service,在node启动时候使用

  • stest 测试框架使用

  • stream-task stream-task供sync同步block使用

  • system 目前提供获取内存相关信息

  • time-service 时间相关封装，MockTimeService供test网络调用这里，时间不是真实时间

  • timeout-join-hanlder thread::JoinHandle提供超时功能

  • utils metrics相关封装

 

config

配置相关文件，account storage 路径相关， Genesis相关配置，挖矿奖励，stdlib framework版本相关，rocksdb相关配置，同步相关策略，最大重试次数，TxPool交易池相关配置

 

consensus

共识相关算法，提供argon, cn, keccak相关算法，其中cn算法没有rust实现(调用C代码)，可能从Monero项目port过来，只有C实现，Monero提供了SSE2SIMD相关优化(也port过来了)，似乎还有JIT的优化这里没有实验， xmrig 做了更复杂的优化(没有port)

executor

executor这里只是处理交易的接口，实际相关的逻辑都在vm-runtime当中

genesis

理解gensis不同的网络是通过不同的starcoin-framework创建的

参考 第6条

miner

俊哥补充

network

network-p2p

network-rpc

node

启动相关逻辑 待补充

rpc

scripts

check_commit.sh 提PR前，本地检查CI相关的有没有问题

check_sync_snapshot_result.py k8s备份相关代码

import_block.sh 导入区块代码

import_snapshot.sh 导入快照代码

install_starcoin_mpm.sh 安装mpm工具脚本

nextest.sh 跑测试相关脚本对比cargo test使用了多核

release.sh 发布release相关的脚本

sync_block.py k8s集群同步区块脚本

sync_snapshot.py k8s集群同步快照脚本

verify_modules.sh 校验区块是否存在问题脚本

state

api

主要提供get_with_proof和get_resource, 理解下MoveResource + DeserializeOwned(待补充)

AcountState主要包括Code_ROOT和Resouce_ROOT,

StateSet是StateTree dump的结果， AccountStateSet是Vec<StateSet>

service

ChainService 提供Get(AccessPath), GetWithProof(AccessPath)两类功能

state-store-api

StateNodeStore ColumnFamily相关 查看storage目录

state-tree

泛型结构,记录了jellyfish-merkle(简单记为JMT)的Root节点(HashValue), updates JMT更新计算的结果, stateCache的change_set_list: Vec<(HashValue, TreeUpdateBatch<K>)>,记录每次更新对应那次 操作,把每次执行交易的历史结果记录下来，保存在持久层

statedb

ChainStateDB的state_tree基于AccountAddress实例化， Cache记录每个AccountAddress对应的更新相关数据AccountStateObject(就是对应的code_tree和resouce_tree,反复调用state-tree), updates记录哪些AccountAddress更新了

storage

storage使用的rocksdb

调用存储相关入口在chain.rs的execute_block_and_save函数

accumulator

BLOCK_ACCUMULATOR_NODE_PREFIX_NAME block_accumulator对应的column family对应的Key是HashValue(AccmulaorNode.hash()),Value对应的AccumulatorNode(使用BCS encode)

TRANSACTION_ACCUMULATOR_NODE_PREFIX_NAME txn_accumulator对应的column family对应的

Key是HashValue(AccmulaorNode.hash()),Value对应的AccumulatorNode(使用BCS encode)

batch

rocksdb writebatch封装，提供写入的原子性

block

BLOCK_PREFIX_NAME 对应的key是HashValue(BlockHeader.id()), value是Block(使用BCS encode),

BLOCK_HEADER_PREFIX_NAME对应的key是HashValue(BlockHeader.id()), value是BlockHeader(使用BCS encode)

BLOCK_BODY_PREFIX_NAME对应的key是HashValue(BlockHeader.id()), value是BlockBody(使用BCS encode), 存在冗余，节省空间已经 废弃

BLOCK_TRANSACTIONS_PREFIX_NAME, 对应的key是HashValue(BlockHeader.id()), value是Vec<HashValue>(HashValue对应Transaction.id())

BLOCK_TRANSACTION_INFOS_PREFIX_NAME 对应的key是HashValue(BlockHeader.id()), value是Vec<HashValue>(HashValue对应的TransactionInfo.id())

block_info

BLOCK_INFO_PREFIX_NAME对应的key是HashVlaue(BlockInfo.block_id), value是BlockInfo(使用BCS encode)

cache_storage

LruCache的封装，目的是提升RocksDB相关性能

chain_info

CHAIN_INFO_PREFIX_NAME 对应几个特殊key,

STARTUP_INFO_KEY 这里主要是作为事务用的，我们的rocksdb没有完全使用rocksdb的write_batch写入，所以STARTUP_INFO_KEY作为一个事务标志确定写完那个高度区块,

GENESIS_KEY获取genesis

STORAGE_VERSION_KEY获取当去db的版本号，结合upgrade来添加删除column family

SNAPSHOT_RANGE_KEY用来处理snapshot导入用的

db_storage

对rocksdb一些功能的封装提供迭代器功能，sync写和nonsync写相关功能

这里和aptos不一样地方在于aptos都是使用write_batch的sync一次写入达到事务的功能，我们分多次写，sync多次性能无法保证所以使用nonsync, 保证事务通过检查START_UP_INFO

state_node

STATE_NODE_PREFIX_NAME 主要给state 待补充

transaction

TRANSACTION_PREFIX_NAME 对应的key是HashValue(Transaction.id()), value是Transaction(使用BCS encode)

transaction_info

TRANSACTION_INFO_PREFIX_NAME_V2 对应的key是HashValue(RichTransactionInfo.id()),value是RichTransactionInfo(BCS encode)

TRANSACTION_INFO_HASH_PREFIX_NAME 对应的key是HashValue(RichTransactionInfo的transaction_hash), value对应的是Vec<HashValue>(RichTransactionInfo.id())这里是因为一个transaction 可能会打包到多个block

CONTRACT_EVENT_PREFIX_NAME 对应的key是HashValue(TransactionInfo.id()), value是Vec<ContractEvent>

stratum

sync

txpool

types

vm

compiler

ModuleBytecodeDowngrader， ScriptBytecodeDowgrader处理Move高版本向低版本字节码转化，主要是升级用

dev

PlaygroudService相关，提供dry_run， call_contract, view_resource相关功能(待补充)

move-coverage

待补充

move-explain

待补充

move-package-manager

move-cli功能封装，并提供了integreation_test功能

move-prover

待补充

natives

提供keccak_256,ripemd160,ed25519_validate_pubkey,ed25519_verify,native_ecrecover,native_append, native_remove,native_reverse,create_signer,destroy_signer,u256等函数给move调用

resource-viewer

待补充

starcoin-transactional-test-harness

integration-test相关，主要是mock了MockStateNodeStore

stdlib

starcoin-framework相关，comipled 目录下分别对应stdlib不同版本的blob文件，提供了检查兼容性的函数

transaction-builder

创建各种转账交易相关函数，主要给dev，test网络测试用，还有faucet

transaction-builder-generator

cpp, java等语言生成交易的sdk包

types

account_config

constants

定义G_ACCOUNT_MODULE,Balance相关,G_BLOCK_MODULE， G_TRANSACTION_MANAGER_MODULE，G_PROLOGUE_NAME， G_EPILOGUE_V2_NAME， EVENT_MODULE， 相关module对应starcoin-framework的sources代码

events

AcceptTokenEvent, DepositEvent,WithdrawEvent, NewBlockEvent, BlockRewardEvent, BurnEvent, ConfigChangeEvent, ProposalCreatedEvent, VoteChangedEvent, MintEvent, UpgradeEvent, 对应starcoin-framework的sources代码

resources

AccountResource, AutoAcceptToken, BalanceResource(余额相关), KeyRotationCapabilityResource, TwoPhaseUpgradeV2Resource(升级相关), ModifyConfigCapabilityResource,WithdrawCapabilityResource

events和resources都和move_resource trait相关

on_chain_config

consensus_config.rs ConsensusConfig(共识相关参数) 对应starcoin-framework Consensusconfig.move

dao_config.rs DaoConfig(投票相关参数), 对应starcoin-framework Dao.move

genesis_gas_config.rs move bytecode gas消耗，native function gas消耗 对应starcoin-framework vmconfig.move

move_lang_version.rs move语言的版本，对应starcoin-framework的LanguageVersion.move

version.rs stdlib版本号，对应starcoin-framework的Version.move

vm_config.rs主要用到VMConfig.move和TransactionPublishOption.move

on_chain_resource

dao

对应Dao.move相关

block_metadata.rs 对应Block.move的BlockMeta, 执行Block交易时候会在前面添加BlockMeta类型的交易

epoch.rs 对应Epoch.move 用来调整difficulty, 相关解释 https://github.com/starcoinorg/sips/blob/master/sip-2/index.zh.md

global_time.rs对应TimeStamp.move的CurrentTimeMilliseconds

nft.rs对应 NFT.move, 相关解释https://github.com/starcoinorg/sips/blob/master/sip-22/index.zh.md

treasury.rs对应Treasury.move 相关解释 https://github.com/starcoinorg/sips/blob/master/sip-5/index.zh.md

serde_helper

serde, deser封装

token

对应STC.move

transaction

分为Package, TransactionScript, ScriptFunction对应TransactionPayLoadType的Package Script, ScriptFunction,

PendingTransaction 作用待补充

access_path.rs 对应AccessPath

block_metadata.rs 这里BlockMetadata用在OpenedBlock待补充

event.rs待补充

gas_schedule.rs gas计费相关，NativeCostIndex是starcoin实现NativeFunction对应的index，G_GAS_CONSTANTS对应VMconfig.move的数据结构starcoin_vm.rs用到

genesis_config.rs 主要提及StdlibVersion和ChainID.move

language_storage_ext.rs 主要FunctionId

sign_message.rs 使用Accout的private key对message签名

transaction_metadata.rs TransactionMetadata记录max_gas_amount，校验执行交易时候gas是否够用

write_set.rs WriteSet记录execute block后，哪些AccountAddress的Resouce更新，删除数据

vm-runtime

data_cache.rs StateViewCache data_view对应原来的存储, data_map对应move execute transaction后新产生的数据

starcoin_vm.rs

执行核心交易 核心数据结构, 其中StarcoinVM version代表stdlib_version, stdlib_version可以通过投 票升级版本，读取通过on_chain_config

move_version代表move对应版本,设置在Genesis.move中

execute_block_and_save 函数， BlockMeta(genesis没有) + UserTrans

vm.execute_block_transactions

先执行BlockMeta交易TransactionBlock::BlockPrologue => vm.process_block_metadata(不消耗gas), 这里主要执行TransactionManager.move的block_prologue,

TransactionBlock::UserTransaction => vm.execute_user_transaction 根据TransactionPayLoad执行execute_script_or_script_function 或者execute_package

execute_script_or_script_function → 先run_prologue, 再执行execute_function, run_epilogue

execute_package → 先run_prologue, 再执行execute_package, run_epilogue,

其中run_prologue执行TransactionManager.move的block_prologue,

run_epilogue执行TransactionManager.move的epilogue_v2,

execute_package会有一个publish_module_bundle_with_option的过程，这里会empty_loader_cache, 这里可能会导致性能损耗，感觉应该是republish时候才执行这个过程

这里block_prologue主要

/// The prologue is invoked at the beginning of every transaction/// It verifies:/// - The account's auth key matches the transaction's public key/// - That the account has enough balance to pay for all of the gas/// - That the sequence number matches the transaction's sequence key

epilogue_v2主要

/// The epilogue is invoked at the end of transactions./// It collects gas and bumps the sequence number

vm.execute_block_transactions 产生的write_set会给ChainStateDB::apply_write_set 写入到存储中

test_native_function.rs 校验最新版本的stdlib 对应的native function和 starcoin实现的native function列表是不是一样

vm-status-translator

翻译相关错误码原因

 

https://starcoin.org/zh/developers/others/

补充move引擎和starcoin的结合

move中提供了两个Trait ModuleResolver, ResourceResolver

execute_function 涉及到interpret bytecode相关执行