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

1
SELECT pin($client, 'finalized') AS client;
Notebook ready in readonly mode.

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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block hash, chain profile, canonicality policy, and durable state identity.

Guidance

Choosing a block selector

Pinning resolves a moving or symbolic selector to an exact block identity.

  • Use finalized or safe when provider-supported finality is more important than the newest head.
  • Use a block number for a human-readable historical boundary.
  • Use a block hash, or a matching number/hash pair, when exact block identity is already known.
  • pending is not a reproducible boundary and may not be supported consistently by providers.

Canonicality and hydration

The pinned identity is durable; attached transport authority can later be replaced without changing which state the CLIENT identifies.

  • Set require_canonical when the provider must confirm that the selected hash belongs to the canonical chain.
  • Historical pinning and later hydration may require archive-capable RPC access.

Statement snapshot

Repeated identical pin requests using the same constructed live-CLIENT wrapper in one SQL statement return the same exact snapshot.

  • Inline pin calls can safely be used across candidate rows without resolving a moving tag per row.
  • Separate client(transport) constructions have separate runtime capabilities and resolve independently.
  • A subsequent SQL statement performs fresh chain validation and selector resolution.

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 whose chain state should be resolved to one exact block.

 required positional
block VARCHAR

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

 required positional
require_canonical BOOLEAN

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

Pinned CLIENT. Returns a pinned CLIENT carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block 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 whose chain state should be resolved to one exact block.

 required positional
block UBIGINT

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

 required positional
require_canonical BOOLEAN

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

Pinned CLIENT. Returns a pinned CLIENT carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block 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 whose chain state should be resolved to one exact block.

 required positional
block BLOCK_NUMBER

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

 required positional
require_canonical BOOLEAN

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

Pinned CLIENT. Returns a pinned CLIENT carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block 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 whose chain state should be resolved to one exact block.

 required positional
block BYTES32

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

 required positional
require_canonical BOOLEAN

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

Pinned CLIENT. Returns a pinned CLIENT carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

Pinned CLIENT. Returns a pinned CLIENT carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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 carrying the resolved block number, block 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 whose chain state should be resolved to one exact 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

When true, reject a block that the provider cannot confirm as canonical.

 required positional

Returns

Name Type
client CLIENT

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

Category and tags

Tag
Client