[Copilot]

Implements 18 asset-layer introspection opcodes for the Arkade script engine, enabling contracts to query asset groups, inputs/outputs, cross-UTXO asset lookups, and intent-specific data from the Arkade Asset V1 packet.

New opcodes

Range	Category	Opcodes
0xe5–0xe8	Packet & Groups	OP_INSPECTNUMASSETGROUPS, OP_INSPECTASSETGROUPASSETID, OP_INSPECTASSETGROUPCTRL, OP_FINDASSETGROUPBYASSETID
0xe9	Metadata	OP_INSPECTASSETGROUPMETADATAHASH
0xea–0xec	Per-Group I/O	OP_INSPECTASSETGROUPNUM, OP_INSPECTASSETGROUP, OP_INSPECTASSETGROUPSUM
0xed–0xef	Cross-Output	OP_INSPECTOUTASSETCOUNT, OP_INSPECTOUTASSETAT, OP_INSPECTOUTASSETLOOKUP
0xf0–0xf2	Cross-Input	OP_INSPECTINASSETCOUNT, OP_INSPECTINASSETAT, OP_INSPECTINASSETLOOKUP
0xf3–0xf6	Intent	OP_INSPECTGROUPINTENTOUTCOUNT, OP_INSPECTGROUPINTENTOUT, OP_INSPECTGROUPINTENTINCOUNT, OP_INSPECTGROUPINTENTIN

Changes

• asset_types.go — AssetPacket, AssetGroup, AssetID, AssetInput, AssetOutput and cross-lookup entry types. Asset IDs are (txid32, gidx_u16) pairs per spec.
• asset_opcodes.go — Handler functions for all 18 opcodes with overflow-safe summation in OP_INSPECTASSETGROUPSUM.
• engine.go — assetPacket *AssetPacket field + SetAssetPacket() setter on Engine.
• opcode.go — Replaced OP_UNKNOWN229–OP_UNKNOWN246 with named constants; wired handlers into opcodeArray.
• opcode_test.go — Updated disasm test for new opcode names.
• asset_opcodes_test.go — 35 tests covering happy paths, error conditions, and group index bounds validation.

Usage

engine, _ := arkade.NewEngine(script, tx, 0, flags, sigCache, hashCache, amount, fetcher)
engine.SetAssetPacket(&arkade.AssetPacket{
    Groups: []arkade.AssetGroup{{
        AssetID: arkade.AssetID{Txid: genesisTxid, Gidx: 0},
        Inputs:  []arkade.AssetInput{{Type: arkade.AssetInputTypeLocal, InputIndex: 0, Amount: 1000}},
        Outputs: []arkade.AssetOutput{{Type: arkade.AssetOutputTypeLocal, OutputIndex: 0, Amount: 1000}},
    }},
    InputAssets:  map[uint32][]arkade.InputAssetEntry{},
    OutputAssets: map[uint32][]arkade.OutputAssetEntry{},
})
engine.Execute()

Original prompt

Arkade Script Opcodes

This document outlines the introspection opcodes available in Arkade Script for interacting with Arkade Assets, along with the high-level API structure and example contracts.

For base opcodes (transaction introspection, arithmetic, cryptographic, etc.), see arkd PR #577.

---

Arkade Asset Introspection Opcodes

These opcodes provide access to the Arkade Asset V1 packet embedded in the transaction.

All Asset IDs are represented as two stack items: (txid32, gidx_u16).

Packet & Groups

Opcode	Stack Effect	Description
OP_INSPECTNUMASSETGROUPS	→ K	Number of groups in the Arkade Asset packet
OP_INSPECTASSETGROUPASSETID k	→ txid32 gidx_u16	Resolved AssetId of group k. Fresh groups use this_txid.
OP_INSPECTASSETGROUPCTRL k	→ -1 | txid32 gidx_u16	Control AssetId if present, else -1
OP_FINDASSETGROUPBYASSETID txid32 gidx_u16	→ -1 | k	Find group index, or -1 if absent

Per-Group Metadata

Opcode	Stack Effect	Description
OP_INSPECTASSETGROUPMETADATAHASH k	→ hash32	Immutable metadata Merkle root (set at genesis)

Per-Group Inputs/Outputs

Opcode	Stack Effect	Description
OP_INSPECTASSETGROUPNUM k source_u8	→ count_u16 or in_u16 out_u16	Count of inputs/outputs. source: 0=inputs, 1=outputs, 2=both
OP_INSPECTASSETGROUP k j source_u8	→ type_u8 data... amount_u64	j-th input/output of group k. source: 0=input, 1=output
OP_INSPECTASSETGROUPSUM k source_u8	→ sum_u64 or in_u64 out_u64	Sum of amounts. source: 0=inputs, 1=outputs, 2=both

OP_INSPECTASSETGROUP return values by type:

Type	type_u8	Additional Data
LOCAL input	0x01	input_index_u32 amount_u64
INTENT input	0x02	txid_32 output_index_u32 amount_u64
LOCAL output	0x01	output_index_u32 amount_u64
INTENT output	0x02	output_index_u32 amount_u64

Cross-Output (Multi-Asset per UTXO)

Opcode	Stack Effect	Description
OP_INSPECTOUTASSETCOUNT o	→ n	Number of asset entries assigned to output o
OP_INSPECTOUTASSETAT o t	→ txid32 gidx_u16 amount_u64	t-th asset at output o
OP_INSPECTOUTASSETLOOKUP o txid32 gidx_u16	→ amount_u64 | -1	Amount of asset at output o, or -1 if not found

Cross-Input (Packet-Declared)

Opcode	Stack Effect	Description
OP_INSPECTINASSETCOUNT i	→ n	Number of assets declared for input i
OP_INSPECTINASSETAT i t	→ txid32 gidx_u16 amount_u64	t-th asset declared for input i
OP_INSPECTINASSETLOOKUP i txid32 gidx_u16	→ amount_u64 | -1	Declared amount for asset at input i, or -1 if not found

Intent-Specific

Opcode	Stack Effect	Description
OP_INSPECTGROUPINTENTOUTCOUNT k	→ n	Number of INTENT outputs in group k
OP_INSPECTGROUPINTENTOUT k j	→ output_index_u32 amount_u64	j-th INTENT output in group k
OP_INSPECTGROUPINTENTINCOUNT k	→ n	Number of INTENT inputs in group k
OP_INSPECTGROUPINTENTIN k j	→ txid_32 output_index_u32 amount_u64	j-th INTENT input in group k

---

High-Level API (Arkade Compile Sugar)

The following API provides syntactic sugar for Arkade Script contracts. Each property/method is documented with its translation to underlying opcodes.

Asset Groups

tx.assetGroups.length      // → OP_INSPECTNUMASSETGROUPS

tx.assetGroups.find(assetId)
                           // → OP_FINDASSETGROUPBYASSETID assetId.txid assetId.gidx
                           //   Returns: group index, or -1 if not found

tx.assetGroups[k].assetId  // → OP_INSPECTASSETGROUPASSETID k
                           //   Returns: { txid: bytes32, gidx: int }

tx.assetGroups[k].isFresh  // → OP_INSPECTASSETGROUPASSETID k
                           //   OP_DROP OP_TXID OP_EQUAL
                           //   True if assetId.txid == this_txid (new asset)

tx.assetGroups[k].control  // → OP_INSPECTASSETGROUPCTRL k
                           //   Returns: AssetId (txid32, gidx_u16), or -1 if no control

// Metadata hash (immutable, set at genesis)
tx.assetGroups[k].metadataHash
                           // → OP_INSPECTASSETGROUPMETADATAHASH k
                           //   Returns the immutable metadata Merkle root

// Counts
tx.assetGroups[k].numInputs
                           // → OP_INSPECTASSETGROUPNUM k 0

tx.assetGroups[k].numOutputs
                           // → OP_INSPECTASSETGROUPNUM k 1

// Sums
tx.assetGroups[k].sumInputs
                           // → OP_INSPECTASSETGROUPSUM...

</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

[louisinger]

copy pasted and improved in #4