ComputeLedger

ComputeLedger

Instalação • Início rápido • Recursos • Referência da CLI • Comparação • Perguntas frequentes

Assine, encadeie por hash e verifique de forma independente o uso de computação, portátil em qualquer provedor.

O ComputeLedger registra o uso de um job de computação (horas de GPU, hardware, duração, tipo de carga de trabalho) como um recibo assinado criptograficamente e o anexa a um livro-razão local à prova de adulteração. Qualquer pessoa pode verificar a autenticidade de um recibo e a integridade do livro-razão sem confiar no emissor e sem adotar a pilha de uma única nuvem, cadeia ou fornecedor.

Instalação

npm install -g computeledger-cli

pip install computeledger-cli

Ambos os pacotes instalam o mesmo comando computeledger. Os recibos são interoperáveis de qualquer forma: um recibo assinado pelo binário npm verifica corretamente com o binário PyPI, e vice-versa.

Início rápido

$ computeledger keys generate --local
Generated Ed25519 keypair.
Public key: COxK/lkoWxWB42QKXjvcHnmBPozH4Oo2JHoOKDjsoU8=
Private key: ./.computeledger/keys/ed25519.pem (mode 600)

$ computeledger record --local --provider aws --hardware nvidia-h100 \
    --duration-seconds 3600 --gpu-hours 1 --workload-type training
Recorded usage receipt 39952199-0897-48b8-92c5-e351f773c83d.

$ computeledger ledger verify --local
Ledger valid: 1 entries, unbroken hash chain.

Ou envolva um job real diretamente, sem necessidade de chamada manual ao record:

computeledger run --local --provider on-prem --hardware nvidia-a100 -- python train.py

run executa o comando envolvido como um subprocesso real (nunca por meio de um shell), mede a duração em tempo real, amostra a utilização da GPU via nvidia-smi quando uma está presente e assina + anexa o recibo resultante automaticamente. Em uma máquina sem GPU NVIDIA, ele ainda produz um recibo apenas com duração.

Entregue o recibo a qualquer pessoa, em qualquer máquina, sem conta no ComputeLedger e sem chamada de rede:

computeledger verify receipt.json

Por que isso existe

O uso de GPU em múltiplas nuvens e provedores não tem um registro portátil e verificável. Um painel de custos informa o que um provedor diz que você usou; ele não permite que um terceiro confirme de forma independente que esse registro não foi alterado posteriormente, e só funciona com os provedores com os quais se integra. O ComputeLedger é um formato de atestado leve e agnóstico de provedor: qualquer processo que possa executar um comando de CLI ou chamar uma ferramenta MCP pode produzir um recibo, e qualquer processo, em qualquer linguagem, pode verificar um.

Isso é deliberadamente restrito. Não compete com marketplaces de GPU, painéis de custo ou plataformas de computação confidencial, todos os quais fazem trabalhos reais e diferentes. Veja a comparação abaixo para saber exatamente onde está a linha.

Recursos

• Assinaturas Ed25519 via bibliotecas criptográficas nativas/padrão do Node e do Python. Sem criptografia personalizada, sem dependência criptográfica externa no lado TypeScript.
• Livro-razão encadeado por hash. Cada recibo incorpora o hash do recibo anterior. Excluir, reordenar ou editar uma entrada histórica quebra a cadeia de uma forma que ledger verify detecta, mesmo que a assinatura da entrada adulterada ainda pareça localmente válida.
• Interoperabilidade entre linguagens por construção. Um recibo assinado pelo binário computeledger do pacote npm verifica corretamente contra o binário computeledger do pacote PyPI. Ambas as implementações serializam o payload do recibo pelo mesmo algoritmo de JSON canônico determinístico antes de aplicar o hash.
• Agnóstico de provedor. Sem conta, sem chave de API, sem dependência de qualquer nuvem ou cadeia específica. Funciona de forma idêntica em um laptop, um cluster local ou qualquer VM na nuvem.
• Nativo para agentes. Todo subcomando suporta --json para saída estruturada, e computeledger mcp inicia um servidor Model Context Protocol expondo record_usage, verify_receipt, list_ledger e verify_ledger como ferramentas chamáveis.
• Sem superfície de injeção por shell. computeledger run -- <command> executa o comando envolvido por meio de um array de argumentos, nunca uma string de shell, então metacaracteres no comando envolvido são inertes.

Referência da CLI

computeledger keys generate [--local]
computeledger keys show [--local] [--json]
computeledger run [--local] [--provider <name>] [--hardware <type>] [--workload-type training|inference|unknown] [--no-record-command] [--json] -- <command...>
computeledger record --provider <name> --hardware <type> --duration-seconds <n> [--gpu-hours <n>] [--flops <n>] [--workload-type <type>] [--local] [--json]
computeledger verify <receipt.json> [--json]
computeledger ledger list [--local] [--json]
computeledger ledger show <id> [--local] [--json]
computeledger ledger verify [--local] [--json]
computeledger export --format json|csv [--out <file>] [--local]
computeledger mcp

Flag	Significado
--local	Usar ./.computeledger no diretório atual em vez de ~/.computeledger
--json	JSON estruturado no stdout em vez de texto legível
--no-record-command	Omitir a string do comando envolvido do recibo (apenas run)

Servidor MCP

O ComputeLedger inclui um servidor Model Context Protocol para que um agente de IA (Claude, Cursor ou qualquer cliente compatível com MCP) possa registrar e verificar recibos de uso de computação diretamente, sem que um humano invoque a CLI manualmente. O pacote Python expõe o servidor como um subcomando em vez de um script de console separado, então computeledger mcp é a invocação real, não computeledger-mcp.

pip install computeledger-cli

Adicione-o à configuração do seu cliente MCP (para Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "computeledger": {
      "command": "uvx",
      "args": ["--from", "computeledger-cli", "computeledger", "mcp"]
    }
  }
}

O servidor expõe quatro ferramentas, correspondendo à CLI uma a uma:

• record_usage(provider, hardware, durationSeconds, gpuHours?, estimatedFlops?, workloadType?, local?): assina uma entrada de uso com a chave Ed25519 local, anexa-a ao livro-razão encadeado por hash e retorna o recibo assinado.
• verify_receipt(receipt): verifica de forma independente a assinatura de um recibo e a integridade do hash.
• list_ledger(local?): lista todos os recibos registrados no livro-razão local.
• verify_ledger(local?): verifica a assinatura de cada entrada e a cadeia de hash ininterrupta em todo o livro-razão.

Exemplo de chamada:

record_usage(provider="lambda-labs", hardware="nvidia-h100", durationSeconds=3600, gpuHours=1, workloadType="training")

O transporte é stdio, então não há nada para hospedar: o cliente MCP inicia o servidor como um subprocesso local. Fonte: python/src/computeledger/mcp/server.py.

O pacote npm expõe as mesmas quatro ferramentas por meio do servidor TypeScript nativo (src/mcp/server.ts), invocado da mesma forma com npx computeledger-cli mcp. Ambas as implementações são verificadas de forma cruzada e interoperáveis, e cada ferramenta retorna o mesmo formato JSON estruturado que o modo --json da CLI produz.

API da biblioteca

import { createReceipt, verifyReceipt, Ledger, verifyChain, loadKeyPair, resolvePaths } from "computeledger-cli";

from computeledger import create_receipt, verify_receipt, Ledger, verify_chain, load_key_pair

Comparação

O ComputeLedger ocupa uma lacuna estreita e específica: um recibo de uso portátil e criptograficamente verificável que não exige adotar a cadeia ou plataforma de um único provedor. Ele não tenta substituir as ferramentas abaixo, cada uma das quais faz um trabalho real e diferente.

	ComputeLedger	SkyPilot	OpenCost	AICert
O que é	Recibos de uso assinados e portáteis	Orquestração de jobs multi-nuvem + custo	Monitoramento de custo Kubernetes/nuvem	Atestado de proveniência de treinamento
Verificação criptográfica	Sim (Ed25519, offline)	Não	Não	Sim (baseado em TPM)
Dependência de provedor	Nenhuma	Orquestra nuvens específicas	Kubernetes/nativo de nuvem	Nenhuma
Histórico à prova de adulteração	Sim (livro-razão encadeado por hash)	Não	Não	Não (artefato único, sem cadeia)
Estrelas no GitHub	Novo	10.441	6.659 (CNCF)	20
Atividade do projeto	Ativo	Ativo	Ativo	Sem commits desde junho de 2024
Nativo para agentes (MCP/--json)	Sim	Parcial (API/SDK)	Não	Não

SkyPilot e OpenCost resolvem problemas reais e adjacentes (executar jobs entre nuvens e visualizar o que custam) em escala e maturidade muito maiores que este projeto. Nenhum produz um registro de uso assinado e verificável de forma independente. O AICert tentou a proveniência de computação de treinamento como uma ferramenta OSS autônoma usando atestado vinculado a TPM e não teve commits desde junho de 2024; o escopo do ComputeLedger é deliberadamente mais restrito (um recibo de uso, não uma estrutura completa de proveniência de treinamento) e envia tanto um pacote npm quanto um PyPI desde o primeiro dia, especificamente para que o formato de recibo não fique preso ao ecossistema de uma única linguagem.

O que é o ComputeLedger e por que ele existe

O ComputeLedger é uma CLI, biblioteca e servidor MCP de código aberto para produzir e verificar registros assinados criptograficamente de uso de computação. Ele existe porque as alegações de uso de computação (horas de GPU consumidas, hardware usado, duração da carga de trabalho) atualmente não têm um formato de prova portátil e verificável offline: um painel de cobrança é tão confiável quanto o provedor que o emite, e cobre apenas esse provedor. Os recibos do ComputeLedger são objetos JSON autossuficientes e assinados que qualquer parte, em qualquer máquina, em qualquer uma das duas implementações de linguagem mantidas independentemente, pode verificar sem chamada de rede ou terceiro confiável.

Perguntas frequentes

O ComputeLedger exige uma conta ou chave de API? Não. Tudo roda localmente. As chaves são geradas e armazenadas na sua própria máquina (~/.computeledger ou ./.computeledger com --local).

Um recibo pode ser forjado? Não sem a chave privada usada para assiná-lo. verify recalcula o hash do payload e verifica a assinatura Ed25519 contra a chave pública incorporada; a própria chave pública faz parte do payload assinado, então substituir uma chave diferente altera o hash e invalida o recibo.

O que acontece se não houver GPU? computeledger run degrada graciosamente: registra a duração em tempo real e o que você especificar em --hardware/--provider, e simplesmente omite as amostras de utilização de GPU se nvidia-smi não for encontrado.

Isso compete com SkyPilot ou OpenCost? Não, veja a tabela de comparação acima. Essas ferramentas resolvem orquestração e visibilidade de custo; o ComputeLedger resolve a verificabilidade independente de uma alegação de uso. Os dois são complementares: use SkyPilot ou OpenCost para orquestração e custo, e adicione o ComputeLedger onde precisar de um registro assinado.

O formato de recibo é um blockchain? É um log local, encadeado por hash e somente anexação, semelhante em espírito a um log Merkle ou uma cadeia de commits git. Não há token, mecanismo de consenso ou rede envolvidos.

O ComputeLedger funciona no Windows? Os pacotes npm e PyPI instalam e rodam em qualquer plataforma suportada pelo Node.js 18+ ou Python 3.10+, incluindo Windows. Uma ressalva: os arquivos de chave privada são gravados com bits de permissão POSIX (modo 600), que restringem o acesso no Linux e macOS; o Windows não aplica o mesmo modelo de permissão POSIX, então o arquivo é gravado, mas a restrição de acesso não tem efeito equivalente lá. O CI atualmente roda apenas no Linux, então Windows e macOS não são testados continuamente upstream.

Posso usar o ComputeLedger para projetos comerciais? Sim. Tanto os pacotes TypeScript quanto Python são licenciados sob Apache-2.0, que permite uso comercial, modificação e redistribuição, inclusive em produtos de código fechado, desde que o aviso de licença e direitos autorais seja preservado.

E se eu precisar de orquestração multi-nuvem ou um painel de custo? O ComputeLedger não faz nenhum dos dois. Ele apenas produz e verifica recibos de uso assinados. Combine-o com SkyPilot para orquestração ou OpenCost para visibilidade de custo se precisar desses.

Contribuindo

Issues e pull requests são bem-vindos. Execute npm test (TypeScript) ou pytest (python/) antes de abrir um PR: ambas as implementações de linguagem incluem uma suíte de testes completa, e qualquer mudança que toque o formato de recibo ou JSON canônico deve manter ambos os lados interoperáveis (veja CONTRIBUTING.md).

Licença

Apache-2.0