debug_call (Func)

Debug a SilverScript contract call by simulating the full spend locally.

Compiles source with debug info, builds a synthetic transaction that spends the contract's P2SH UTXO with a call to the chosen entrypoint, and executes it through SilverScript's source-level debug engine. The result reports pass/fail; on failure it includes a source-level report with the failing statement, the call stack, and the decoded variables (locals, arguments, contract state) in each frame. console.log output is captured either way.

This simulates script validation on a synthetic transaction: it does not touch the network and says nothing about fees, mass, or maturity.

The tx scenario dict takes the following keys:

Transaction keys

• 'version' (int): Transaction version (default 1).
• 'lock_time' (int): Transaction lock time (default 0).
• 'active_input_index' (int): The input being debugged (default 0).
• 'inputs' (list[dict]): Required. At least one input.
• 'outputs' (list[dict]): The transaction outputs.

Input keys

• 'utxo_value' (int): Required. The spent UTXO value in sompi.
• 'covenant_id' (bytes | str): 32 bytes or hex.
• 'state' (dict): Contract state fields carried by the spent UTXO.
• 'constructor_args' (list): Constructor arguments for this input, overriding the top-level 'constructor_args'. The active input's are the ones the debugged call runs against.
• 'prev_txid' (bytes | str), 'prev_index' (int), 'sequence' (int), 'sig_op_count' (int): Outpoint and input metadata.
• 'signature_script' (bytes | str), 'utxo_script' (bytes | str): Raw script overrides.

Output keys

• 'value' (int): Required. The output value in sompi.
• 'covenant_id' (bytes | str): 32 bytes or hex.
• 'authorizing_input' (int): Index of the authorizing input.
• 'state' (dict): The post-transition contract state to verify.
• 'constructor_args' (list): Constructor arguments for this output, overriding the top-level 'constructor_args'.
• 'script' (bytes | str), 'p2pk_pubkey' (bytes | str): Raw script overrides.

PARAMETER	DESCRIPTION
source	The SilverScript contract source. TYPE: str
function_name	The entrypoint to call. Defaults to the contract's first entrypoint in source order, which need not be abi[0]: the ABI is ordered by name. For covenant functions, use the source-level name (e.g. "add"). TYPE: Optional[str] DEFAULT: None
args	Native Python values matching the entrypoint's parameters. For covenant transition functions the leading State parameter is synthesized from the scenario's output states, so pass only the source-level arguments after it. TYPE: Optional[Any] DEFAULT: None
constructor_args	Native Python values for the contract's constructor parameters, used for inputs and outputs that do not name their own. Defaults to the active input's 'constructor_args'. TYPE: Optional[Any] DEFAULT: None
tx	Transaction scenario dict (see above). Defaults to a single-input, single-output spend of the contract. TYPE: Optional[Any] DEFAULT: None
trace	When True, record a per-statement execution trace on result.trace: each executed statement with its source line, enclosing function, and the variables in scope when it was reached. Tracing changes what is recorded, not what executes. One statement never appears: a covenant transition's return(State { ... }), whose produced state the engine verifies as a whole instead of stepping (as in the CLI debugger). A transition body that is only that return therefore traces to nothing, while its other statements trace normally. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
DebugCallResult	The simulation outcome. Script failures are reported in the result, not raised. TYPE: DebugCallResult

RAISES	DESCRIPTION
SilverScriptError	If compilation fails, the entrypoint or an argument is invalid, or the tx scenario is malformed.

Note

Experimental. SilverScript and these bindings are under active development; the API may change in breaking ways between releases.