Add optional machine-readable output for ots info / ots verify#163
Open
bilalobe wants to merge 2 commits intoopentimestamps:masterfrom
Open
Add optional machine-readable output for ots info / ots verify#163bilalobe wants to merge 2 commits intoopentimestamps:masterfrom
bilalobe wants to merge 2 commits intoopentimestamps:masterfrom
Conversation
Introduce optional --json output for `ots info` and `ots verify' without changing the default human-readable CLI behavior. For `verify --json`, distinguish incomplete/pending timestamps from hard verification failure with a dedicated pending exit code: - 0 = verified - 2 = pending / not yet complete - 1 = hard failure Also add tests for the JSON helpers and document the new mode in the README.
There was a problem hiding this comment.
Pull request overview
Adds optional machine-readable JSON output to the OpenTimestamps client CLI for ots info and ots verify, enabling automation to consume structured verification/status data without parsing human-oriented strings.
Changes:
- Introduces
--jsonflag forots infoandots verifyand emits structured JSON payloads. - Adds JSON serialization helpers for detached timestamps and attestations, plus a JSON-oriented verify path with exit-code semantics.
- Adds unit tests and README examples for the new JSON output.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
otsclient/cmds.py |
Implements JSON serialization and --json output paths for info/verify, including exit-code computation. |
otsclient/args.py |
Adds --json CLI flags for verify and info. |
otsclient/tests/test_json_output.py |
Adds tests covering JSON serialization and JSON-mode verify exit codes. |
README.md |
Documents the new --json usage with examples and exit-code notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
otsclient/cmds.py
Outdated
Comment on lines
+108
to
+113
| upgrade_timestamp(timestamp, args) | ||
|
|
||
| result = { | ||
| "status": "failed", | ||
| "verified": False, | ||
| "upgraded": True, |
otsclient/cmds.py
Outdated
| verify_result = verify_timestamp_json(detached_timestamp.timestamp, args) | ||
| result.update(verify_result) | ||
| result["exit_code"] = 0 if verify_result["verified"] else ( | ||
| EXIT_VERIFY_PENDING if verify_result["status"] == "pending" else EXIT_VERIFY_FAILED |
otsclient/cmds.py
Outdated
Comment on lines
+652
to
+653
| else: | ||
| result["target"] = {"type": "file", "value": args.timestamp_fd.name[:-4]} |
Comment on lines
+108
to
+155
| Machine-readable JSON output is also available for `info`: | ||
|
|
||
| $ ots info --json examples/two-calendars.txt.ots | ||
| { | ||
| "command": "info", | ||
| "file": "examples/two-calendars.txt.ots", | ||
| "file_digest": "efaa174f68e59705757460f4f7d204bd2b535cfd194d9d945418732129404ddb", | ||
| "hash_algorithm": "sha256", | ||
| "timestamp": { | ||
| "attestation_count": 2, | ||
| "attestations": [ | ||
| { | ||
| "calendar": "https://alice.btc.calendar.opentimestamps.org", | ||
| "status": "pending", | ||
| "type": "PendingAttestation" | ||
| }, | ||
| { | ||
| "calendar": "https://bob.btc.calendar.opentimestamps.org", | ||
| "status": "pending", | ||
| "type": "PendingAttestation" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
|
|
||
| Likewise, `verify` can emit structured status output: | ||
|
|
||
| $ ots --no-bitcoin verify --json examples/incomplete.txt.ots | ||
| { | ||
| "command": "verify", | ||
| "status": "pending", | ||
| "verified": false, | ||
| "exit_code": 2, | ||
| "attestations": [ | ||
| { | ||
| "chain": "bitcoin", | ||
| "height": 428648, | ||
| "reason": "bitcoin_disabled", | ||
| "status": "manual_check_required", | ||
| "type": "BitcoinBlockHeaderAttestation" | ||
| }, | ||
| { | ||
| "calendar": "https://alice.btc.calendar.opentimestamps.org", | ||
| "status": "pending", | ||
| "type": "PendingAttestation" | ||
| } | ||
| ] | ||
| } |
Set `upgraded` from the actual upgrade result, treat `manual_check_required` as a non-hard-failure pending exit, make the JSON target path explicit in `verify_command()`, and update the README examples to match the emitted schema.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds optional machine-readable output for the OpenTimestamps client CLI.
Initial scope:
ots info --jsonots verify --jsonDefault human-readable output is unchanged.
Motivation
Downstream automation currently has to parse human-oriented strings such as:
Pending confirmation in Bitcoin blockchainBitcoinBlockHeaderAttestation(...)Success! Bitcoin block ...Failed! Timestamp not completeThat makes integrations brittle and makes it hard to distinguish:
--no-bitcoin)This PR adds a structured interface for those cases without touching the timestamp format or consensus-critical proof
logic.
Scope
This PR adds:
ots info --jsonots verify --jsonIt does not:
Behavior
ots info --jsonOutputs structured information about a detached timestamp, including:
ots verify --jsonOutputs structured verification information, including:
For
verify --json, the exit codes are:0= verified2= pending / not yet complete1= hard verification failureThis allows downstream tools to distinguish incomplete timestamps from genuinely invalid or failed verification cases.
Design notes
This change is intentionally implemented in the client CLI layer (
otsclient.args/otsclient.cmds) and does notmodify
opentimestamps.core.That keeps the feature focused on operability and integration rather than proof semantics.
Why this is useful
This improves:
Tests
Added tests for:
verify --jsonpending statusverify --jsonverified statusDocumentation
README examples were added for:
ots info --jsonots verify --jsonRelated
This is related to #127, but intentionally narrower.
This PR does not attempt to solve explorer-backed verification.
It provides a stable machine-readable CLI surface that makes downstream tooling and future verifier work much easier.