[Hendobox]

Description

Slice 3 of #439: bump finance/wallet_screening to 2.1.0 (stay on 2.x per #447 feedback) with offline-direct screening and optional live Chainalysis/TRM verification. Softens instructions.md toward summarize/gate (no schema-wire lecture).
Acceptance criteria → diff:

• No ETHERSCAN_API_KEY → metadata.mode: offline_direct_only against bundled sanctions + direct malicious entity check → skill.py; test_offline_direct_only_without_etherscan, test_offline_direct_sanctioned_address
• Optional CHAINALYSIS_API_KEY / TRM_SANCTIONS_API_KEY → risk_details.live_verification[]; soft-fail into metadata.warnings; live hit elevates to critical / DENY → _screen_chainalysis / _screen_trm; test_live_trm_sanctioned_elevates_to_critical, test_live_chainalysis_rate_limit_warns.
• Manifest env_vars: Etherscan optional; new optional live keys → manifest.yaml; catalog + docs/usage/api_keys.md
• Version / catalog / CHANGELOG / TBD skill-history → 2.1.0 hubs + docs/skills/finance/wallet_screening.md
  Out of this PR ([Skill Upgrade]: finance/wallet_screening v2.0 #439 slice 4): provenance.report_hash, remaining docs/test-vector polish.

Type of Change

• New Skill — new registry bundle under skills/.
• Skill Upgrade — changes to an existing skill under skills/.
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs, README, CONTRIBUTING only
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — PyPI wheel, pyproject.toml, MANIFEST.in
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Fixes #… or Refs #…)
• Scope matches the issue — no unrelated refactors
• Contribution complies with Legal notice and code ownership (original work, MIT license grant, no malicious logic)
• python -m black --check ., flake8, and ruff check . pass locally (or CI-equivalent subset)
• pytest skills/ and pytest tests/ pass locally when relevant
• CHANGELOG.md updated under [Unreleased] when user-visible behavior changes
• examples/README.md updated if this PR adds, renames, or removes a runnable script
• Ran pytest tests/test_registry_docs.py when skills, examples index, or agent-loops matrix changed
• Ran pytest tests/test_skill_docs.py when catalog Usage Examples or provider snippets changed

New or updated skill

Skip unless this PR adds or changes files under skills/.

Bundle and metadata

• Skill at skills/<category>/<skill_name>/ (from templates/python_skill/ or equivalent)
• manifest.yaml: name (full ID), version, description, parameters, constitution, real issuer
• Optional: short_description, issuer.github, issuer.org, requirements, env_vars

Effect, Directive, Assurance

• Deterministic skill.py (Effect; no ad-hoc LLM-generated execution paths)
• instructions.md (Directive) explains when and how to use the skill
• card.json (Presentation) issuer matches manifest when present
• test_skill.py (Assurance) covers execution and schema expectations
• SkillLoader.load_skill("<category>/<skill_name>") succeeds (or deps documented)

Documentation and catalog

• docs/skills/<category>/<skill_name>.md, category hub row, row in docs/skills/README.md, and docs/sitemap.md
• Usage Examples for Gemini, Claude, OpenAI, DeepSeek, Ollama per skill usage template

Constitution and safety (skills only)

Read-only screening. Offline path uses bundled public lists only. Live Chainalysis/TRM are optional and soft-fail; they do not sign or broadcast. Hosts should halt on DENY and require a person on REVIEW. Not legal advice.

Related Issues

Refs #439

[rosspeili]

LGTM @Hendobox! very clean implementation.

Two minor suggestions before merge:

1. In _generate_report_data(), un-nest risk_factors.append(...) from if risk_level != "critical": so live match evidence is still recorded into risk_factors[] when the address already triggered an offline sanctions hit.
2. In _screen_chainalysis(), check identifications[0].get("name") or identifications[0].get("category") so detail is not None on positive hits.

Once these are in,

[Hendobox]

@rosspeili both review notes are in on the latest commit:

1. LIVE_SANCTIONS_MATCH risk factors are always recorded when a live provider flags the address, including when offline already set critical / DIRECT_SANCTIONS_MATCH.
2. Chainalysis detail now falls back to identifications[0].name / .category on positive hits.

Ready for re-review when you have a moment.

After merge on #439: happy to do slice 4 (provenance.report_hash + docs/test polish) next, or close the milestone if you consider v2.1 enough — your call.

[rosspeili]

@Hendobox thanks a lot, there is a minor conflict at wallet screening, but can patch later, nothing crazy. I think we can merge this as is as v2.1.0.

Regarding next steps on #439, yes, please go ahead with a targeted follow-up PR for Slice 4 (provenance.report_hash canonical SHA-256 integrity hash + final test/docs polish), once Slice 4 is merged, we can officially close the #439 milestone and pin to 2.1.0.

Thank you for the great work on this! This is very clean cut <3