Suggested
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.

Scalar functionLive RPC Client

Example

Live RPC

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

API reference

pin(CLIENT, VARCHAR | UBIGINT | BLOCK_NUMBER | BYTES32) # Pin

Pin by block tag, number or hash.

Exact signatures (4)
  • pin(CLIENT, VARCHAR)
  • pin(CLIENT, UBIGINT)
  • pin(CLIENT, BLOCK_NUMBER)
  • pin(CLIENT, BYTES32)

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 | UBIGINT | BLOCK_NUMBER | 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, VARCHAR | UBIGINT | BLOCK_NUMBER | BYTES32, BOOLEAN) # Pin Tag Canonicality

Pin by block tag, number or hash and apply the requested canonicality policy.

Exact signatures (4)
  • pin(CLIENT, VARCHAR, BOOLEAN)
  • pin(CLIENT, UBIGINT, BOOLEAN)
  • pin(CLIENT, BLOCK_NUMBER, BOOLEAN)
  • pin(CLIENT, BYTES32, BOOLEAN)

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 | UBIGINT | BLOCK_NUMBER | 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.

pin(CLIENT, UBIGINT | BLOCK_NUMBER, BYTES32) # Pin

Pin only when the block number and block hash identify the same block.

Exact signatures (2)
  • pin(CLIENT, UBIGINT, BYTES32)
  • pin(CLIENT, BLOCK_NUMBER, BYTES32)

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_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, UBIGINT | BLOCK_NUMBER, BYTES32, BOOLEAN) # Pin

Pin a matching number and hash pair and apply the requested canonicality policy.

Exact signatures (2)
  • pin(CLIENT, UBIGINT, BYTES32, BOOLEAN)
  • pin(CLIENT, BLOCK_NUMBER, BYTES32, BOOLEAN)

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_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.

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.