paperproof-sdk-py 0.2.2__py3-none-any.whl

paperproof/__init__.py

@@ -0,0 +1,270 @@
+# Copyright (c) 2026 PaperProof Labs
+# SPDX-License-Identifier: Apache-2.0
+
+from paperproof.abort_explainer import (
+    MoveAbortInfo,
+    PaperProofErrorExplanation,
+    explain_paperproof_error,
+    format_paperproof_error_explanation,
+    parse_move_abort,
+)
+from paperproof.analytics import (
+    artifact_records_to_csv,
+    artifact_records_to_dataframe,
+    artifact_records_to_dicts,
+    artifact_records_to_jsonl,
+    batch_get_objects,
+    collect_events,
+    event_page_to_dicts,
+    event_to_dict,
+    events_to_csv,
+    events_to_dataframe,
+    events_to_dicts,
+    events_to_jsonl,
+    query_governance_history,
+    query_recent_activity,
+    record_to_dict,
+    records_to_csv,
+    records_to_dataframe,
+    records_to_dicts,
+    records_to_jsonl,
+    vote_records_to_csv,
+    vote_records_to_dataframe,
+    vote_records_to_dicts,
+    vote_records_to_jsonl,
+    write_events_csv,
+    write_events_jsonl,
+    write_records_csv,
+    write_records_jsonl,
+)
+from paperproof.client import PaperProofClient, create_paperproof_sdk
+from paperproof.coin_utils import CoinLike, CoinSelection, CoinSummary, select_coins_covering, summarize_coins
+from paperproof.constants import (
+    ARTIFACT_TYPES,
+    COMMENT_MODE,
+    COMMENT_STATUS,
+    DIRECT_AUTHORITY_MODE,
+    FEE_LEVEL,
+    GOVERNANCE,
+    MAX_PROPOSER_THRESHOLD,
+    MIN_PROPOSER_THRESHOLD,
+    PROTOCOL_LIMITS,
+    SERIES_STATUS,
+    TREE_STATUS,
+)
+from paperproof.deployment_update import (
+    DEFAULT_DEPLOYMENT_MANIFEST_BASE_URL,
+    DEFAULT_MAINNET_DEPLOYMENT_MANIFEST_URL,
+    check_deployment_update,
+    default_deployment_manifest_url,
+    format_deployment_update_check,
+)
+from paperproof.deployment_verifier import format_deployment_verification, verify_deployment
+from paperproof.deployments import MAINNET_DEPLOYMENT
+from paperproof.errors import (
+    ContractCallError,
+    EventParseError,
+    InsufficientBalanceError,
+    InvalidAddressError,
+    InvalidInputError,
+    InvalidObjectIdError,
+    InvalidPackageIdError,
+    NetworkError,
+    ObjectNotFoundError,
+    PaperProofError,
+    TransactionBuildError,
+    TransactionExecutionError,
+    WalletNotConnectedError,
+)
+from paperproof.events import (
+    extract_add_version_result,
+    extract_artifact_status_changed_event,
+    extract_comment_result,
+    extract_comment_status_changed_event,
+    extract_events_by_struct,
+    extract_like_event,
+    extract_owner_transferred_event,
+    extract_proposal_executed_event,
+    extract_proposal_expired_event,
+    extract_proposal_finalized_event,
+    extract_proposal_result,
+    extract_protocol_paused_changed_event,
+    extract_publish_result,
+    extract_tree_status_changed_event,
+    extract_unlike_event,
+    extract_vote_cast_events,
+    extract_vote_claimed_event,
+)
+from paperproof.pysui_executor import (
+    PysuiCompileResult,
+    PysuiExecutionProvider,
+    PysuiExecutionResult,
+    PysuiTransactionCompiler,
+    PysuiTransactionService,
+    normalize_pysui_execution_result,
+)
+from paperproof.query import PaperProofQueryClient, SeriesDetails
+from paperproof.query_providers import (
+    DEFAULT_GRAPHQL_ENDPOINTS,
+    FallbackQueryProvider,
+    GraphQLQueryProvider,
+    JsonRpcQueryProvider,
+    PaperProofQueryProvider,
+)
+from paperproof.robust import RetryOptions, robust_execute_plan, with_retries
+from paperproof.service import PaperProofService
+from paperproof.sync import PaperProofSyncClient, create_paperproof_sync_sdk, run_sync
+from paperproof.transactions import MoveCall, TransactionPlan
+from paperproof.types import (
+    ArtifactPublishedRecord,
+    EventPage,
+    EventQuery,
+    MyVoteRecord,
+    Pagination,
+    PaperProofQueryTransport,
+    PaperProofTransport,
+    TransactionExecutionResult,
+)
+from paperproof.walrus_robust import (
+    ContentPublishResult,
+    ContentReadResult,
+    PaperProofContentService,
+    RobustWalrusClient,
+    WalrusExtendResult,
+    WalrusTransferResult,
+    WalrusUploadResult,
+    blob_digest,
+)
+from paperproof.watch import PaperProofEventWatcher, PaperProofWatchClient, WatchOptions
+
+__all__ = [
+    "ARTIFACT_TYPES",
+    "ArtifactPublishedRecord",
+    "COMMENT_MODE",
+    "COMMENT_STATUS",
+    "CoinLike",
+    "CoinSelection",
+    "CoinSummary",
+    "ContentPublishResult",
+    "ContentReadResult",
+    "ContractCallError",
+    "DEFAULT_GRAPHQL_ENDPOINTS",
+    "DEFAULT_DEPLOYMENT_MANIFEST_BASE_URL",
+    "DEFAULT_MAINNET_DEPLOYMENT_MANIFEST_URL",
+    "DIRECT_AUTHORITY_MODE",
+    "FEE_LEVEL",
+    "FallbackQueryProvider",
+    "GOVERNANCE",
+    "GraphQLQueryProvider",
+    "EventPage",
+    "EventQuery",
+    "EventParseError",
+    "InsufficientBalanceError",
+    "InvalidAddressError",
+    "InvalidInputError",
+    "InvalidObjectIdError",
+    "InvalidPackageIdError",
+    "JsonRpcQueryProvider",
+    "MAINNET_DEPLOYMENT",
+    "MAX_PROPOSER_THRESHOLD",
+    "MIN_PROPOSER_THRESHOLD",
+    "MoveAbortInfo",
+    "MoveCall",
+    "MyVoteRecord",
+    "NetworkError",
+    "ObjectNotFoundError",
+    "PROTOCOL_LIMITS",
+    "Pagination",
+    "PaperProofErrorExplanation",
+    "PaperProofClient",
+    "PaperProofContentService",
+    "PaperProofError",
+    "PaperProofQueryProvider",
+    "PaperProofQueryClient",
+    "PaperProofQueryTransport",
+    "PaperProofService",
+    "PaperProofSyncClient",
+    "PaperProofEventWatcher",
+    "PaperProofWatchClient",
+    "PaperProofTransport",
+    "PysuiCompileResult",
+    "PysuiExecutionProvider",
+    "PysuiExecutionResult",
+    "PysuiTransactionCompiler",
+    "PysuiTransactionService",
+    "RetryOptions",
+    "RobustWalrusClient",
+    "SERIES_STATUS",
+    "SeriesDetails",
+    "TREE_STATUS",
+    "TransactionPlan",
+    "TransactionBuildError",
+    "TransactionExecutionResult",
+    "TransactionExecutionError",
+    "WalletNotConnectedError",
+    "WatchOptions",
+    "WalrusExtendResult",
+    "WalrusTransferResult",
+    "WalrusUploadResult",
+    "artifact_records_to_csv",
+    "artifact_records_to_dataframe",
+    "artifact_records_to_dicts",
+    "artifact_records_to_jsonl",
+    "batch_get_objects",
+    "blob_digest",
+    "check_deployment_update",
+    "collect_events",
+    "create_paperproof_sdk",
+    "create_paperproof_sync_sdk",
+    "default_deployment_manifest_url",
+    "event_page_to_dicts",
+    "event_to_dict",
+    "events_to_csv",
+    "events_to_dataframe",
+    "events_to_dicts",
+    "events_to_jsonl",
+    "extract_add_version_result",
+    "extract_artifact_status_changed_event",
+    "extract_comment_result",
+    "extract_comment_status_changed_event",
+    "extract_events_by_struct",
+    "extract_like_event",
+    "extract_owner_transferred_event",
+    "extract_proposal_executed_event",
+    "extract_proposal_expired_event",
+    "extract_proposal_finalized_event",
+    "extract_proposal_result",
+    "extract_protocol_paused_changed_event",
+    "extract_publish_result",
+    "extract_tree_status_changed_event",
+    "extract_unlike_event",
+    "extract_vote_cast_events",
+    "extract_vote_claimed_event",
+    "explain_paperproof_error",
+    "format_deployment_update_check",
+    "format_deployment_verification",
+    "format_paperproof_error_explanation",
+    "normalize_pysui_execution_result",
+    "parse_move_abort",
+    "query_governance_history",
+    "query_recent_activity",
+    "record_to_dict",
+    "records_to_csv",
+    "records_to_dataframe",
+    "records_to_dicts",
+    "records_to_jsonl",
+    "robust_execute_plan",
+    "run_sync",
+    "select_coins_covering",
+    "summarize_coins",
+    "verify_deployment",
+    "vote_records_to_csv",
+    "vote_records_to_dataframe",
+    "vote_records_to_dicts",
+    "vote_records_to_jsonl",
+    "with_retries",
+    "write_events_csv",
+    "write_events_jsonl",
+    "write_records_csv",
+    "write_records_jsonl",
+]

paperproof/abort_explainer.py

@@ -0,0 +1,352 @@
+# Copyright (c) 2026 PaperProof Labs
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+MODULE_HINTS = (
+    "comments",
+    "governance_voting",
+    "governance",
+    "publishing",
+    "validation",
+    "artifact_types",
+)
+
+
+@dataclass(frozen=True)
+class MoveAbortInfo:
+    package_id: str | None = None
+    module: str | None = None
+    code: int | None = None
+
+
+@dataclass(frozen=True)
+class PaperProofErrorExplanation:
+    matched: bool
+    title: str
+    detail: str
+    raw: str
+    suggestion: str | None = None
+    move_abort: MoveAbortInfo | None = None
+
+
+_ABORTS: dict[str, dict[int, tuple[str, str, str]]] = {
+    "comments": {
+        2: (
+            "Comments tree is not open",
+            "The target comments tree is locked or archived.",
+            "Read the tree status and only add comments when it is open.",
+        ),
+        3: (
+            "Parent comment not found",
+            "The parent comment id does not exist in this tree.",
+            "Use root parent id 0 or read the comment node before replying.",
+        ),
+        4: ("Empty on-chain comment", "The on-chain comment content is empty.", "Provide non-empty comment text."),
+        5: (
+            "On-chain comment too large",
+            "The on-chain comment exceeds the tree limit.",
+            "Use a blob comment or shorten the content.",
+        ),
+        8: (
+            "Not the comments tree owner",
+            "The signer is not authorized as tree owner.",
+            "Use the current tree owner account or transfer tree ownership first.",
+        ),
+        11: (
+            "Comment not found",
+            "The requested comment id does not exist in this tree.",
+            "Read the comment node or check the tree id/comment id pair.",
+        ),
+        12: (
+            "Comment status permission denied",
+            "The signer is not authorized for this transition.",
+            "Authors can delete their own comments; tree owners can hide/delete according to protocol rules.",
+        ),
+        16: (
+            "Insufficient PPRF proof balance for like",
+            "The supplied PPRF coin has less than the required proof balance.",
+            "Use a PPRF coin with at least 1 PPRF.",
+        ),
+        17: (
+            "Already liked",
+            "The liker has already liked this artifact.",
+            "Call unlike before liking again, or treat the current state as success.",
+        ),
+        18: ("Not liked yet", "The liker has no existing like to remove.", "Check has_liked before calling unlike."),
+        20: (
+            "Parent comment is not active",
+            "Replies are not allowed under hidden or deleted comments.",
+            "Reply to an active comment or the root.",
+        ),
+        25: (
+            "Root comment is immutable",
+            "The root comment cannot be hidden or deleted.",
+            "Only update real user comment ids.",
+        ),
+        26: (
+            "Deleted comment is final",
+            "A deleted comment cannot be restored or changed.",
+            "Treat deleted as a terminal state.",
+        ),
+    },
+    "governance": {
+        3: (
+            "Not governance authority",
+            "The signer is not the configured governance authority.",
+            "Use governance voting flow or the current governance authority account.",
+        ),
+        6: (
+            "Invalid registry binding",
+            "One or more governance objects are from different registries.",
+            "Use canonical objects from the same PaperProof deployment.",
+        ),
+        11: (
+            "Insufficient fee payment",
+            "The supplied payment coin is below the required fee.",
+            "Select a larger SUI coin or split enough SUI before the call.",
+        ),
+        12: (
+            "Not upgrade authority",
+            "The signer is not the configured upgrade authority.",
+            "Use the upgrade authority account or migrate authority through governance.",
+        ),
+        16: (
+            "Direct authority disabled",
+            "Direct authority mode does not allow this operation.",
+            "Use the governance proposal execution path.",
+        ),
+        18: (
+            "Governance config already bound",
+            "The vault already has a GovernanceConfig binding.",
+            "Do not initialize/bind GovernanceConfig twice.",
+        ),
+    },
+    "governance_voting": {
+        2: (
+            "Proposal creation paused",
+            "Governance proposal creation is paused.",
+            "Wait for governance to unpause proposal creation.",
+        ),
+        5: (
+            "Proposal not active",
+            "The proposal is not in active voting state.",
+            "Read proposal status before voting or finalizing.",
+        ),
+        6: (
+            "Already voted",
+            "This voter has already voted on the proposal.",
+            "Claim locked tokens after finalization instead of voting again.",
+        ),
+        7: (
+            "Voting has not ended",
+            "The proposal cannot be finalized until its end epoch.",
+            "Wait until end_epoch or use early resolve only when outcome is determinable.",
+        ),
+        8: ("Proposal already finalized", "The proposal is no longer active.", "Do not finalize/resolve it again."),
+        9: (
+            "Proposal not passed",
+            "Only passed executable proposals can be executed.",
+            "Check proposal status and votes before execution.",
+        ),
+        11: (
+            "Proposal already executed",
+            "The proposal action has already been consumed.",
+            "Do not execute the same proposal twice.",
+        ),
+        13: (
+            "Invalid governance vault/config binding",
+            "Proposal, config, vault, or executor cap are not bound to the same registry.",
+            "Use canonical deployment objects and resolve proposal object id from GovernanceConfig.",
+        ),
+        17: (
+            "Another active proposal exists",
+            "Only one active proposal is allowed at a time.",
+            "Finalize, execute, expire, or wait for the active proposal before creating another.",
+        ),
+        19: (
+            "No vote to claim",
+            "The signer has no locked vote tokens to claim for this proposal.",
+            "Check voter address and proposal id.",
+        ),
+        20: (
+            "Voting power below minimum",
+            "The supplied PPRF coin is below minimum voting stake.",
+            "Use a PPRF coin with at least MIN_VOTE_STAKE.",
+        ),
+        21: (
+            "Proposer stake below threshold",
+            "The proposer PPRF coin is below the proposer threshold.",
+            "Use enough PPRF or lower the threshold through governance.",
+        ),
+        31: (
+            "Invalid proposal/config binding",
+            "The proposal object is not bound to the supplied GovernanceConfig.",
+            "Resolve the proposal object id via get_proposal_object_id.",
+        ),
+    },
+    "publishing": {
+        1: (
+            "Publishing is paused",
+            "The root paused flag blocks publish and add-version calls.",
+            "Wait until publishing is unpaused.",
+        ),
+        5: ("Invalid artifact type", "The artifact type is not supported.", "Use ARTIFACT_TYPES constants."),
+        6: (
+            "Artifact type disabled",
+            "The selected artifact type is disabled for publishing/versioning.",
+            "Choose an enabled type or wait for governance to enable it.",
+        ),
+        8: (
+            "Invalid governance vault",
+            "The supplied GovernanceVault is not the canonical object bound to root.",
+            "Use MAINNET_DEPLOYMENT.objects.governance_vault.",
+        ),
+        9: (
+            "Invalid fee manager",
+            "The supplied FeeManager is not the canonical object bound to root.",
+            "Use MAINNET_DEPLOYMENT.objects.fee_manager.",
+        ),
+        21: (
+            "Not series owner",
+            "Only the series owner can perform this action.",
+            "Use the current owner account or transfer ownership first.",
+        ),
+        23: (
+            "Invalid comments tree",
+            "The comments tree does not belong to the series.",
+            "Use the comments_tree_id emitted when the series was published.",
+        ),
+        25: (
+            "Too many versions",
+            "The series reached MAX_VERSIONS_PER_SERIES.",
+            "Start a new series or stop appending versions.",
+        ),
+        29: (
+            "Duplicate metadata key",
+            "metadata_extensions contains duplicate keys.",
+            "Deduplicate keys before building the transaction.",
+        ),
+    },
+    "validation": {
+        10: (
+            "Empty content hash",
+            "content_hash must not be empty.",
+            "Provide the content hash for the artifact bytes.",
+        ),
+        11: (
+            "Empty Walrus blob id",
+            "walrus_blob_id must not be empty.",
+            "Upload to Walrus first or use an explicit smoke-test fallback.",
+        ),
+        12: (
+            "Empty Walrus blob object id",
+            "walrus_blob_object_id must not be empty.",
+            "Pass the Walrus blob object id.",
+        ),
+        14: ("Empty title", "The artifact title/project name is empty.", "Provide a non-empty title."),
+        17: ("Empty author list", "At least one author is required.", "Provide authors."),
+        21: ("Text too long", "A text field exceeds protocol limits.", "Run SDK validation before submitting."),
+        23: ("Empty vector item", "A vector field contains an empty item.", "Remove empty authors/keywords/tags."),
+    },
+}
+
+
+def _raw_text(error: object) -> str:
+    if isinstance(error, BaseException):
+        return str(error)
+    if isinstance(error, str):
+        return error
+    try:
+        return json.dumps(error, ensure_ascii=False, default=str)
+    except TypeError:
+        return repr(error)
+
+
+def parse_move_abort(error: object) -> MoveAbortInfo | None:
+    raw = _raw_text(error)
+    if not raw:
+        return None
+    package_match = re.search(r"(0x[0-9a-fA-F]{1,64})::[A-Za-z_][A-Za-z0-9_]*::", raw)
+    module_match = re.search(r"(?:MoveAbort|move abort).*?([A-Za-z_][A-Za-z0-9_]*)\s*[,):]", raw, re.IGNORECASE)
+    module = module_match.group(1) if module_match and module_match.group(1) in MODULE_HINTS else None
+    if module is None:
+        module = next((hint for hint in MODULE_HINTS if f"::{hint}::" in raw or hint in raw), None)
+    code_match = (
+        re.search(r"abort(?:ed)?(?: with)?(?: code)?\s*(0x[0-9a-fA-F]+|\d+)", raw, re.IGNORECASE)
+        or re.search(r"code[:=]\s*(0x[0-9a-fA-F]+|\d+)", raw, re.IGNORECASE)
+        or re.search(r",\s*(\d+)\s*\)", raw)
+    )
+    code = None
+    if code_match:
+        text = code_match.group(1)
+        code = int(text, 16) if text.lower().startswith("0x") else int(text)
+    if not package_match and module is None and code is None:
+        return None
+    return MoveAbortInfo(
+        package_id=package_match.group(1) if package_match else None,
+        module=module,
+        code=code,
+    )
+
+
+def explain_paperproof_error(error: object) -> PaperProofErrorExplanation:
+    raw = _raw_text(error)
+    move_abort = parse_move_abort(error)
+    if move_abort and move_abort.module and move_abort.code is not None:
+        known = _ABORTS.get(move_abort.module, {}).get(move_abort.code)
+        if known:
+            title, detail, suggestion = known
+            return PaperProofErrorExplanation(True, title, detail, raw, suggestion, move_abort)
+    if re.search(
+        r"insufficient.*(balance|coin|fund)|not enough.*(balance|coin|fund)|balance.*too low", raw, re.IGNORECASE
+    ):
+        return PaperProofErrorExplanation(
+            True,
+            "Insufficient coin balance",
+            "The signer or selected payment/proof coin does not hold enough balance for this operation.",
+            raw,
+            "Top up the required SUI/WAL/PPRF balance or select a larger coin before submitting.",
+            move_abort,
+        )
+    if re.search(r"insufficient.*gas|gas", raw, re.IGNORECASE):
+        return PaperProofErrorExplanation(
+            True,
+            "Gas or coin selection problem",
+            "The transaction failed while selecting or charging gas/payment coins.",
+            raw,
+            "Check SUI balance for gas and avoid using the same coin for multiple roles.",
+            move_abort,
+        )
+    if re.search(r"needs to be rebuilt|unavailable for consumption|current version", raw, re.IGNORECASE):
+        return PaperProofErrorExplanation(
+            True,
+            "Transaction needs rebuilding",
+            "A shared or owned input object advanced to a newer version before submission.",
+            raw,
+            "Rebuild the transaction and retry.",
+            move_abort,
+        )
+    return PaperProofErrorExplanation(
+        False,
+        "Unrecognized PaperProof/Sui error",
+        raw or "The SDK could not extract a detailed error message.",
+        raw,
+        "Inspect the transaction digest, Sui explorer details, and PaperProof object bindings.",
+        move_abort,
+    )
+
+
+def format_paperproof_error_explanation(explanation: PaperProofErrorExplanation) -> str:
+    abort = explanation.move_abort
+    abort_text = (
+        f" module={abort.module or 'unknown'} code={abort.code if abort.code is not None else 'unknown'}"
+        if abort
+        else ""
+    )
+    suggestion = f" Suggestion: {explanation.suggestion}" if explanation.suggestion else ""
+    return f"{explanation.title}.{abort_text} {explanation.detail}{suggestion}"