View this page as Markdown

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.

Example

Needs RPC · RPC required

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

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

pin(CLIENT, VARCHAR) # Pin

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

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block VARCHAR

Block tag, height, or hash selected by the overload's SQL type.

 required positional

Returns

Name Type
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 overloads

pin(CLIENT, VARCHAR, BOOLEAN) # Pin Tag Canonicality

Resolves a block tag and applies the requested canonicality policy.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block VARCHAR

Block tag, height, or hash selected by the overload's SQL type.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, UBIGINT) # Pin

Pins the exact block returned for block_number.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block UBIGINT

Block tag, height, or hash selected by the overload's SQL type.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, UBIGINT, BOOLEAN) # Pin Number Canonicality

Pins a block number and applies the requested canonicality policy.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block UBIGINT

Block tag, height, or hash selected by the overload's SQL type.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BLOCK_NUMBER) # Pin

Pins a BLOCK_NUMBER value returned by an EVM relation.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BLOCK_NUMBER

Block tag, height, or hash selected by the overload's SQL type.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BLOCK_NUMBER, BOOLEAN) # Pin Hash Canonicality

Pins a BLOCK_NUMBER value and applies the requested canonicality policy.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BLOCK_NUMBER

Block tag, height, or hash selected by the overload's SQL type.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BYTES32) # Pin

Pins the exact block identified by block_hash.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BYTES32

Block tag, height, or hash selected by the overload's SQL type.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BYTES32, BOOLEAN) # Pin Hash Canonicality

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

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BYTES32

Block tag, height, or hash selected by the overload's SQL type.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

Show 4 more overloads
pin(CLIENT, UBIGINT, BYTES32) # Pin

Pins only when block_number and block_hash identify the same block.

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block UBIGINT

Block tag, height, or hash selected by the overload's SQL type.

 required positional
block_hash BYTES32

Exact block hash that must identify the same block as block_number.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, UBIGINT, BYTES32, BOOLEAN) # Pin

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

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block UBIGINT

Block tag, height, or hash selected by the overload's SQL type.

 required positional
block_hash BYTES32

Exact block hash that must identify the same block as block_number.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BLOCK_NUMBER, BYTES32) # Pin

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

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BLOCK_NUMBER

Block tag, height, or hash selected by the overload's SQL type.

 required positional
block_hash BYTES32

Exact block hash that must identify the same block as block_number.

 required positional

Returns

Name Type
client CLIENT

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

pin(CLIENT, BLOCK_NUMBER, BYTES32, BOOLEAN) # Pin

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

Note: The client must have a transport attached.

Inputs

Name Type Use
client CLIENT

Live CLIENT to resolve to one block.

 required positional
block BLOCK_NUMBER

Block tag, height, or hash selected by the overload's SQL type.

 required positional
block_hash BYTES32

Exact block hash that must identify the same block as block_number.

 required positional
require_canonical BOOLEAN

Set to true to reject a block the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

Category and tags

Tag
Client