# decode_function_data

Validates and decodes selector-prefixed function calldata into typed SQL columns defined by the function's ABI inputs.

Canonical HTML: <https://determica.com/docs/functions/decode_function_data>

- Kind: table function
- Category: [Contracts and ABI](/docs/category/contracts-and-abi.md)
- Tags: ABI

Validates and decodes selector-prefixed function calldata into typed SQL columns defined by the function's ABI inputs.

## Overload 1: decode_function_data(JSON, VARCHAR, BYTES)

```sql
decode_function_data(JSON, VARCHAR, BYTES)
```

The ABI and function selection must be constant because they define the result columns; calldata may vary by input row.

- Kind: table
- Execution context: Offline
- Behavior: Abi Calldata Decode
- Execution modes: Offline
- Input shape: Scalar Or Relation
- Planning contract: Bind Time Schema
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Dynamic Table
- Schema stability: Abi Dependent
- Stability: Stable
- Side effects: None documented

### Requirements

- foldable_abi
- foldable_function_selection
- selector_prefixed_calldata

### Inputs

- `abi` (JSON; required; positional) — Contract ABI JSON containing the selected function inputs.
- `function_or_selector` (VARCHAR; required; positional) — Constant name, canonical signature, or 4-byte selector identifying one ABI function.
- `calldata` (BYTES; required; positional) — Raw calldata beginning with the 4-byte function selector followed by standard ABI argument bytes.

### Relation input

The ABI and function-selection columns must be constant across the relation. calldata may vary by row.

### Relation columns

- `abi` (JSON) — Foldable ABI JSON column that defines the input schema. Required
- `function_or_selector` (VARCHAR) — Foldable function name, canonical signature, or 4-byte selector column. Required
- `calldata` (BYTES) — Row-varying selector-prefixed calldata. Required

```sql
SELECT *
FROM decode_function_data((
  SELECT
    '[{"type":"function","name":"transfer","inputs":[{"name":"to","type":"address"},{"name":"value","type":"uint256"}]}]'::JSON AS abi,
    'transfer(address,uint256)' AS function_or_selector,
    from_hex('a9059cbb000000000000000000000000000000000000000000000000000000000000dead0000000000000000000000000000000000000000000000000000000000000001')::BYTES AS calldata
));
```

### Returns

Selector metadata plus ABI-derived input columns

Returns calldata_selector, function_name, function_signature, then one column per selected function input.

- `calldata_selector` (BYTES4) — The validated 4-byte selector read from calldata.
- `function_name` (VARCHAR) — Selected ABI function name.
- `function_signature` (VARCHAR) — Canonical signature of the selected ABI function.

### Dynamic columns

- Source: abi + function_or_selector
- Names: ABI input names, or input{index} for unnamed inputs
- Types: Mapped from ABI input types
- Description: After calldata_selector, function_name, and function_signature, returns one column per selected function input.

Selector metadata plus ABI-derived input columns. Returns calldata_selector, function_name, function_signature, then one column per selected function input.

### Examples

_Local SQL · Local_

```sql
-- Encode transfer calldata for 2,500 USDC, then decode it
WITH payload AS (
  SELECT encode_function_data(
    '[{"type":"function","name":"transfer","inputs":[{"name":"to","type":"address"},{"name":"value","type":"uint256"}]}]'::JSON,
    'transfer(address,uint256)',
    '0x000000000000000000000000000000000000dEaD'::ADDRESS,
    parse_units('2500', 6)
  ) AS calldata
)
SELECT decoded.*
FROM payload
CROSS JOIN LATERAL decode_function_data(
  '[{"type":"function","name":"transfer","inputs":[{"name":"to","type":"address"},{"name":"value","type":"uint256"}]}]'::JSON,
  'transfer(address,uint256)',
  payload.calldata
) AS decoded;
```

## Guidance

### Inspect function calldata

Use decode_function_data to inspect calldata before simulation, signing, or policy evaluation. The function validates the calldata selector before decoding inputs.

- Use a canonical signature such as transfer(address,uint256) when overloads are possible.
- Decoded ERC-20 amount columns are raw token units; format them separately for display.

```sql
WITH abi AS (
  SELECT '[{
    "type": "function",
    "name": "transfer",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" }
    ]
  }]'::JSON AS abi_json
), payload AS (
  SELECT encode_function_data(
    abi_json,
    'transfer(address,uint256)',
    '0x000000000000000000000000000000000000dEaD'::ADDRESS,
    parse_units('2500', 6)
  ) AS calldata
  FROM abi
)
SELECT decoded.*
FROM payload
CROSS JOIN LATERAL decode_function_data(
  '[{
    "type": "function",
    "name": "transfer",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" }
    ]
  }]'::JSON,
  'transfer(address,uint256)',
  payload.calldata
) AS decoded;
```

### Choose the right ABI primitive

Choose by byte framing and direction: selector construction, standard arguments, calldata, packed bytes, raw words, calldata decoding, and return-data decoding are distinct operations.

- function_selector hashes already-canonical signature text exactly; function_selector_json builds a canonical signature from one JSON ABI fragment first.
- encode_function_args emits selector-free standard ABI arguments; encode_function_data prefixes those same bytes with the 4-byte selector.
- abi_encode_packed concatenates compact scalar encodings without standard ABI offsets, lengths, or 32-byte padding; evm_abi_word always emits exactly one padded 32-byte word.
- decode_function_data consumes and validates selector-prefixed calldata inputs; call_decode consumes selector-free function return bytes.

```sql
SELECT
  function_selector('transfer(address,uint256)') AS selector,
  encode_function_data(
    '[{"type":"function","name":"transfer","inputs":[{"type":"address"},{"type":"uint256"}]}]'::JSON,
    'transfer(address,uint256)',
    '0x000000000000000000000000000000000000dEaD'::ADDRESS,
    1::UINT256
  ) AS calldata;
```

## Related functions

- [encode_function_data](/docs/functions/encode_function_data.md) — Usually After
- [function_selector](/docs/functions/function_selector.md) — See Also
- [function_selector_json](/docs/functions/function_selector_json.md) — See Also
- [call_decode](/docs/functions/call_decode.md) — Alternative