Stellarcarbon审计数据库

具有监控和审计功能的核心数据库。

这是一个独立的工具，可以通过命令行界面用于监控和审计Stellarcarbon账户。我们建议对于不想管理自己的Python安装的用户，通过Docker使用sc-audit。如果您已经运行了较新的Python版本，安装Python包可能是最方便的选项。

可以通过多种方式对sc-audit及其数据进行编程访问。要将其与Python项目集成，只需将sc-audit包作为依赖项包含即可。其他环境能够使用CLI进行基本命令，并且可以使用文件系统或与其SQLite数据库的连接来获取数据并进行进一步处理。

Docker使用方法

首先从ghcr.io拉取最新发布的镜像

docker pull ghcr.io/stellarcarbon/sc-audit

这个Docker镜像旨在进行单命令使用。它不会保持进程运行，一旦完成就退出。将其数据卷挂载到本地以持久化数据库，并使用--rm选项运行容器，以避免停止容器的垃圾。

您需要在每次使用会话的开始让数据库跟上其数据源。

docker run --rm -v sc-data:/opt/data ghcr.io/stellarcarbon/sc-audit catch-up

--help标志提供了CLI的交互式文档。它还可以与（子）命令结合使用，以获取其参数的信息。

$ docker run --rm -v sc-data:/opt/data ghcr.io/stellarcarbon/sc-audit --help

Connecting to database sqlite+pysqlite:////opt/data/sc-audit.sqlite3...
Usage: sc-audit [OPTIONS] COMMAND [ARGS]...

  CLI for Stellarcarbon Audit tool

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  catch-up  Let the DB catch up with the data sources
  load      Load data from their original sources
  schema    Database schema migration commands
  view      View the state of Stellarcarbon assets and transactions

由于docker run前缀相当长，您可能发现声明一个shell别名很方便，这样您就可以像CLI在容器外运行一样运行命令。

alias sc-audit="docker run --rm -v sc-data:/opt/data ghcr.io/stellarcarbon/sc-audit"

请参考您的操作系统或shell文档，了解如何将此别名持久化到shell会话中。配置别名后，您就可以像通过Python安装一样使用sc-audit。继续阅读以了解提供的命令的更多信息。

Python使用

安装

从PyPI安装sc-audit包和CLI

pip install sc-audit

请注意，如果您将sc-audit安装到virtualenv中（推荐），则sc-audit脚本仅在激活此virtualenv时可用。

设置

数据库需要使用最新的DB模式进行初始化。我们使用Alembic来管理迁移。在使用sc-audit之前，请确保您的本地DB已使用最新的模式定义创建。

sc-audit schema upgrade

要从Python代码实现相同的功能，您可以这样做：

from sc_audit import migrations

migrations.upgrade(revision="head")

升级sc-audit到较新版本后，可能还需要升级DB模式。重复上述说明以运行任何新的迁移。提供的Docker镜像已经负责运行DB迁移，因此无需手动运行。

加载数据

在使用任何视图命令之前，使用catch-up命令以获得Stellarcarbon的库存和沉没交易的一致视图是最简单的方法。这会将所有可用源的最新数据加载到数据库中。该命令是幂等的，因此可以重复运行而不出问题。然而，如果该命令非常频繁地使用，可能会遇到对外部源请求的速率限制。

每次要检查Stellarcarbon账户的当前状态时，请使用catch-up命令。

sc-audit catch-up

load命令对于正常使用不是必需的，但它们提供了一些特殊用例。例如，您可以仅监控退役或沉没交易。

Usage: sc-audit load [OPTIONS] COMMAND [ARGS]...

  Load data from their original sources

Options:
  --help  Show this message and exit.

Commands:
  associations      Load associations into the DB
  distribution-txs  Load distribution outflows into the DB
  minted-blocks     Load minted blocks into the DB
  retirements       Load retirements into the DB
  sinking-txs       Load sinking transactions into the DB

加载数据的Python API包含在sc_audit.loader模块中。查看sc_audit.loader.__main__.catch_up_from_sources函数以了解如何将新记录仅加载到数据库中的灵感。

查看数据

inventory和sink视图分别组合了不同类型的源数据。库存是通过取Stellarcarbon已发行的信用块，并从其剩余信用中扣除已退役的信用来重建的。

Usage: sc-audit view inventory [OPTIONS]

  View Stellarcarbon's current or historical inventory of eco-credits

Options:
  -f, --format [df|csv|json]  The output format for this view  [default: df]
  --omit-empty                Don't show empty minted blocks
  --until-date [%Y-%m-%d]     Reconstruct the inventory on the given date
  --help                      Show this message and exit.

默认输出格式是可读的表格视图。它目前较宽，最终也会变长。因此，我们建议使用不带换行符的屏幕分页器来舒适地查看库存表。

sc-audit view inventory | less -S

csv和json都可用作机器可读输出格式。常见用法是将输出传递给另一个命令或将输出重定向到文件。

sc-audit view inventory -f csv > sc-inventory-$(date +"%Y-%m-%d").csv

Python API位于sc_audit.views.inventory，并返回库存表作为Pandas DataFrame。

def view_inventory(omit_empty: bool = False, until_date: dt.date | None = None) -> pd.DataFrame

沉没视图将沉没交易与其关联的退役（存储为SinkStatus对象）结合起来。它可以以多种方式进行过滤。

Usage: sc-audit view sink [OPTIONS]

  View sinking transactions and their retirement status

Options:
  -f, --format [df|csv|json]  The output format for this view  [default: df]
  --funder TEXT               Only show transactions for the given funder
                              address
  --recipient TEXT            Only show transactions for the given recipient
                              address
  --from-date [%Y-%m-%d]      Filter transactions that happened on or after
                              the given date
  --before-date [%Y-%m-%d]    Filter transactions that happened before the
                              given date
  --finalized BOOLEAN         Filter by retirement status
  --help                      Show this message and exit.

与库存视图一样，请使用水平滚动。

sc-audit view sink | less -S

或将机器可读输出重定向到文件。

sc-audit view sink -f json > sc-sink-$(date +"%Y-%m-%d").json

Python API位于sc_audit.views.sink_status，返回以Pandas DataFrame格式的下沉交易表。

def view_sinking_txs(
        for_funder: str | None = None,
        for_recipient: str | None = None, 
        from_date: dt.date | None = None,
        before_date: dt.date | None = None,
        finalized: bool | None = None,
        cursor: int | None = None,
        limit: int | None = None,
        order: Literal['asc', 'desc'] = 'desc',
) -> pd.DataFrame

retirements视图显示已完成的退休和退休信用的基本属性。它不显示这些信用来自哪些区块以及哪些下沉交易被这些退休所填充。其过滤器与下沉视图非常相似。

Usage: sc-audit view retirements [OPTIONS]

  View finalized retirements and the attributes of the retired credits

Options:
  -f, --format [df|csv|json]  The output format for this view  [default: df]
  --beneficiary TEXT          Only show retirements for the given beneficiary
                              address
  --from-date [%Y-%m-%d]      Filter retirements that happened on or after the
                              given date
  --before-date [%Y-%m-%d]    Filter retirements that happened before the
                              given date
  --project INTEGER           Filter by impact project
  --help                      Show this message and exit.

Python API位于sc_audit.views.retirement，返回退休表作为Pandas DataFrame。

def view_retirements(
        for_beneficiary: str | None = None, 
        from_date: dt.date | None = None,
        before_date: dt.date | None = None,
        project: int | None = None,
        cursor: int | None = None,
        limit: int | None = None,
        order: Literal['asc', 'desc'] = 'desc',
) -> pd.DataFrame

配置

在sc-audit中无需配置太多。有两个变量可以通过环境变量覆盖。

开发

为希望为此项目做出贡献的开发者提供说明。

先决条件

• 支持的Python安装（v3.12+）
• Python Poetry

设置

在克隆此git仓库后，使用以下命令安装依赖项

poetry install

您还需要安装为该仓库配置的git钩子

pre-commit install

版本管理

我们使用常规提交消息来帮助保持变更日志的更新。您上面安装的git钩子将强制执行任何提交的轻量级规范。这些提交消息用于在发布过程中自动更新变更日志。

Release Please跟踪自上次发布以来main分支的所有提交。它创建一个发布PR，适当地递增版本号并添加到变更日志中。一旦发布PR被合并，就会创建GitHub发布，并将sc-audit包的新版本发布到PyPI。同时构建并发布到ghrc.io的Docker镜像。