Skip to content

feat: Add Karma as pluggable verifiable evaluator for ERC-8183 - #33

Open
GoldenShihao wants to merge 1 commit into
bnb-chain:mainfrom
GoldenShihao:feat/karma-verifiable-evaluator
Open

feat: Add Karma as pluggable verifiable evaluator for ERC-8183#33
GoldenShihao wants to merge 1 commit into
bnb-chain:mainfrom
GoldenShihao:feat/karma-verifiable-evaluator

Conversation

@GoldenShihao

@GoldenShihao GoldenShihao commented May 21, 2026 •
edited
Loading

Copy link
Copy Markdown

What

Adds Karma as a pluggable verifiable evaluator for ERC-8183 Agentic Commerce.

  • Introduces bnbagent[karma] extra (pip install "bnbagent[karma]")
  • New bnbagent/extras/karma/ module with KarmaEvaluator
  • Uses Karma SDK's execute_with_proof() to generate signed receipt + auditable evidence bundle
  • Maps results to EvaluatorRouter.submit_verdict() and OptimisticPolicy
  • Supports x402 payment hook and enhanced dispute resolution

Why

Strengthens BNB Chain's current optimistic settlement model by adding strong cryptographic proof-of-execution and verifiable evidence, complementing ERC-8183 and x402.

Demo Video

Karma Verifiable Evaluator - Full Testnet Demo

Shows end-to-end flow: Tool execution → Signed Receipt → Evidence Bundle → KarmaEvaluator → ERC-8183 settlement.

How to Use

from bnbagent.evaluators.karma import KarmaEvaluator

evaluator = KarmaEvaluator(karma_endpoint="...")
result, receipt, bundle = await evaluator.execute_and_submit(job_id, tool_call)

Checklist

  • 399 tests passing (0 regression)
  • No breaking changes to core SDK
  • Documentation updated

Related Repo: https://github.com/AtoB101/Karma

mac_02 mac_02
feat: Add Karma as pluggable verifiable evaluator for ERC-8183
ef5be2b 
Integrates Karma Trust Protocol's signed receipt + evidence bundle
verification into the ERC-8183 settlement lifecycle.

Why
---
ERC-8183's OptimisticPolicy (silence-approves) works for simple cases
but lacks cryptographic proof that the provider actually executed the
work correctly. Karma Trust Protocol adds verifiable execution with
per-tool-call signed receipts, Merkle-verifiable evidence bundles,
and an independent Runtime that checks hash consistency.

What
----
- bnbagent/extras/karma/evaluator.py — KarmaEvaluator (off-chain
  verifier), KarmaBNBVerifier (bridge to ERC8183Client),
  KarmaEvidenceStore, KarmaReceiptSigner, and evidence encoding
  helpers (build_karma_evidence_bytes, parse_karma_evidence,
  verify_karma_receipt_digest).

- examples/karma_integration.py — Full E2E demo: simulate Karma
  tool execution → negotiate → upload bundle → create ERC-8183 job
  → submit deliverable → Karma verify → settle on-chain.

- tests/test_extras_karma.py — 24 tests covering store CRUD,
  receipt signing, evaluator payload/verdict interpretation,
  evidence encoding, and verifier evidence serialization.

- pyproject.toml — Added 'karma' extra (pip install bnbagent[karma]).

- README.md + ARCHITECTURE.md — New 'Karma Verifiable Evaluator'
  section documenting the integration.

Design
------
- Off-chain verification via Karma Runtime REST API (/v1/verify).
- No new on-chain contracts — uses existing OptimisticPolicy +
  EvaluatorRouter. Karma acts as a pre-settlement oracle.
- Evidence bytes written to router.settle(evidence) create a
  permanent on-chain audit trail linking back to Karma verification.
- KarmaEvaluator has zero Web3 dependencies — callers can use it
  standalone or compose via KarmaBNBVerifier.

Install: pip install "bnbagent[karma]"
@hashdit-bot

hashdit-bot Bot commented May 21, 2026

Copy link
Copy Markdown

Pull Request Review

This PR adds a new optional karma integration to the BNBAgent SDK, introducing bnbagent.extras.karma with a full off-chain verification flow (KarmaEvaluator) and an ERC-8183 bridge (KarmaBNBVerifier) that can verify deliverables and conditionally settle on-chain. It also updates package metadata (pyproject.toml) to expose a new pip extra and expands documentation in README.md and ARCHITECTURE.md with architecture, usage, and quickstart guidance. A comprehensive new test file validates evaluator behavior, evidence encoding/decoding, and helper utilities, plus a full end-to-end example script was added.

Sensitive Content

Private Key / Seed Phrase / Mnemonic / Secret Material:

  • karm...cret (API key / secret material example) in README.md — shown as api_key="karma_secret" in quick example
  • karm...cret (API key / secret material example) in bnbagent/extras/karma/__init__.py — shown as api_key="karma_secret" in docstring quickstart
  • karm...cret (API key / secret material example) in bnbagent/extras/karma/evaluator.py — shown as api_key="karma_worker-001_secret" in usage docstring
  • karm...cret (API key / secret material example) in examples/karma_integration.py — shown as KARMA_API_KEY="karma_worker-001_secret" in script docs

Security Issues

No serious security issues detected.

Generated by Hashdit Bot. This tool can absolutely NOT replace manual audits.

@hiltonmccarthy21-wq

hiltonmccarthy21-wq commented May 21, 2026

Copy link
Copy Markdown

I Hilton Mccarthy personally want to thank u Mr Agent, u job wath u doing is outstanding, I want us to personally video call each other so we can develop I bond,but the problem is I don't have I pc,I try my best to do everything on my android fone,and it's very difficult. I humblely plea I we can just can withdraw all my transactions I made,so that I can by I pc ,to connect with you sir,thank u very much Sir

@GoldenShihao GoldenShihao mentioned this pull request May 22, 2026
Merged
7 tasks
@GoldenShihao

GoldenShihao commented May 23, 2026

Copy link
Copy Markdown
Author

我希尔顿麦卡锡亲自想感谢你，经纪人先生，你的工作很出色，我想让我们亲自视频通话，这样我们就可以发展我的联系，但问题是我没有电脑，我尽力在我的安卓手机上做所有事情，这非常困难。我谦卑地恳求，我们可以撤回我所做的所有交易，这样我就可以通过我的电脑与您联系，先生，非常感谢先生

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@GoldenShihao @hiltonmccarthy21-wq