# pin

Resolves a live CLIENT to one exact block and returns a pinned CLIENT for repeatable state reads. Pin by tag, number, hash, or a matching number/hash pair, with optional canonicality enforcement. Identical normalized requests using the same constructed live-CLIENT wrapper share one resolution within a SQL statement; separate client(transport) constructions resolve independently, and a later statement resolves the selector again.

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

- Kind: scalar function
- Category: [Clients and state contexts](/docs/category/clients-and-state-contexts.md)
- Tags: Client

Resolves a live CLIENT to one exact block and returns a pinned CLIENT for repeatable state reads. Pin by tag, number, hash, or a matching number/hash pair, with optional canonicality enforcement. Identical normalized requests using the same constructed live-CLIENT wrapper share one resolution within a SQL statement; separate client(transport) constructions resolve independently, and a later statement resolves the selector again.

## Overload 1: pin(CLIENT, VARCHAR)

```sql
pin(CLIENT, VARCHAR)
```

Resolves latest, safe, finalized, earliest, or pending.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (VARCHAR; required; positional) — Block tag, height, or hash selected by the overload's SQL type.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 2: pin(CLIENT, VARCHAR, BOOLEAN)

```sql
pin(CLIENT, VARCHAR, BOOLEAN)
```

Resolves a block tag and applies the requested canonicality policy.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin Tag Canonicality
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (VARCHAR; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 3: pin(CLIENT, UBIGINT)

```sql
pin(CLIENT, UBIGINT)
```

Pins the exact block returned for block_number.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (UBIGINT; required; positional) — Block tag, height, or hash selected by the overload's SQL type.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 4: pin(CLIENT, UBIGINT, BOOLEAN)

```sql
pin(CLIENT, UBIGINT, BOOLEAN)
```

Pins a block number and applies the requested canonicality policy.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin Number Canonicality
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (UBIGINT; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 5: pin(CLIENT, BLOCK_NUMBER)

```sql
pin(CLIENT, BLOCK_NUMBER)
```

Pins a BLOCK_NUMBER value returned by an EVM relation.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BLOCK_NUMBER; required; positional) — Block tag, height, or hash selected by the overload's SQL type.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 6: pin(CLIENT, BLOCK_NUMBER, BOOLEAN)

```sql
pin(CLIENT, BLOCK_NUMBER, BOOLEAN)
```

Pins a BLOCK_NUMBER value and applies the requested canonicality policy.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin Hash Canonicality
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BLOCK_NUMBER; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 7: pin(CLIENT, BYTES32)

```sql
pin(CLIENT, BYTES32)
```

Pins the exact block identified by block_hash.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BYTES32; required; positional) — Block tag, height, or hash selected by the overload's SQL type.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 8: pin(CLIENT, BYTES32, BOOLEAN)

```sql
pin(CLIENT, BYTES32, BOOLEAN)
```

Pins a block hash and optionally rejects a non-canonical block.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin Hash Canonicality
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BYTES32; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 9: pin(CLIENT, UBIGINT, BYTES32)

```sql
pin(CLIENT, UBIGINT, BYTES32)
```

Pins only when block_number and block_hash identify the same block.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (UBIGINT; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `block_hash` (BYTES32; required; positional) — Exact block hash that must identify the same block as block_number.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 10: pin(CLIENT, UBIGINT, BYTES32, BOOLEAN)

```sql
pin(CLIENT, UBIGINT, BYTES32, BOOLEAN)
```

Pins the matching number/hash pair and optionally rejects a non-canonical block.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (UBIGINT; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `block_hash` (BYTES32; required; positional) — Exact block hash that must identify the same block as block_number.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 11: pin(CLIENT, BLOCK_NUMBER, BYTES32)

```sql
pin(CLIENT, BLOCK_NUMBER, BYTES32)
```

Pins only when a BLOCK_NUMBER value and block_hash identify the same block.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BLOCK_NUMBER; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `block_hash` (BYTES32; required; positional) — Exact block hash that must identify the same block as block_number.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Overload 12: pin(CLIENT, BLOCK_NUMBER, BYTES32, BOOLEAN)

```sql
pin(CLIENT, BLOCK_NUMBER, BYTES32, BOOLEAN)
```

Pins a matching BLOCK_NUMBER/hash pair and optionally rejects a non-canonical block.

- Kind: scalar
- Execution context: Offline
- Behavior: Pin
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io, durable_state_write

### Requirements

- client_with_transport

### Inputs

- `client` (CLIENT; required; positional) — Live CLIENT to resolve to one block.
- `block` (BLOCK_NUMBER; required; positional) — Block tag, height, or hash selected by the overload's SQL type.
- `block_hash` (BYTES32; required; positional) — Exact block hash that must identify the same block as block_number.
- `require_canonical` (BOOLEAN; required; positional) — Set to true to reject a block the provider cannot confirm as canonical.

### Returns

Pinned CLIENT

Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

- `client` (CLIENT)

Pinned CLIENT. Returns a pinned CLIENT with its resolved block number and hash, chain profile, canonicality policy, and durable state identity.

## Guidance

### Choosing a block selector

Pinning replaces a moving or symbolic selector with one block number and hash.

- Use finalized or safe to prefer a provider-confirmed block over the newest head.
- Use a block number when you know the block height.
- Use a block hash, or a matching number/hash pair, when exact block identity is already known.
- Do not use pending for repeatable reads. Provider support for pending also varies.

### Canonicality and hydration

A pinned CLIENT keeps the same state identity when its attached TRANSPORT changes.

- Set require_canonical when the provider must confirm that the selected hash belongs to the canonical chain.
- Pinning or fetching historical state may require archive-capable RPC access.

### Statement snapshot

Within one SQL statement, identical pin requests on the same live CLIENT resolve to the same block.

- Use the same inline pin call across candidate rows. Determica does not resolve the moving tag for each row.
- Each client(transport) call creates a separate runtime capability, so the calls resolve independently.
- A later SQL statement validates the chain and resolves the selector again.

## Additional examples

```sql
SELECT pin($client, 'finalized') AS client;
```