From a46318c3ac27c0c92b490e7efd1dc1927380c06d Mon Sep 17 00:00:00 2001 From: Edgars Date: Wed, 13 May 2026 12:12:47 +0100 Subject: [PATCH] docs: surface 'timestamp' in Transaction Context for search The new Transaction Context page used 'datetime' in headings and 'timestamp' only in code/body, so searching the docs site for 'timestamp' (the term most devs reach for) ranked the page poorly or missed it entirely. - Mention 'timestamp' explicitly in the page intro. - Rename '## Time in a contract' to '## Time and Timestamps'. - Add '### Transaction Timestamp' heading with a small table covering the three forms (Unix seconds, datetime object, ISO string). --- .../features/transaction-context.mdx | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/pages/developers/intelligent-contracts/features/transaction-context.mdx b/pages/developers/intelligent-contracts/features/transaction-context.mdx index 0f1b04ba..5e67e2f1 100644 --- a/pages/developers/intelligent-contracts/features/transaction-context.mdx +++ b/pages/developers/intelligent-contracts/features/transaction-context.mdx @@ -2,7 +2,7 @@ import { Callout } from "nextra-theme-docs"; # Transaction Context -Every contract execution has access to information about the transaction that triggered it — caller addresses, value, chain ID, and the transaction's datetime. This page covers what is available, how to access it, and what is *not* available. +Every contract execution has access to information about the transaction that triggered it — caller addresses, value, chain ID, and the transaction **timestamp** (datetime). This page covers how to read the current time, get a Unix timestamp, access caller and tx metadata, and what is *not* exposed (block number, gas, wall-clock). ## `gl.message` — typed accessors @@ -47,12 +47,23 @@ if gl.message_raw['is_init']: Prefer `gl.message` for the common fields — it gives you autocompletion and type checking. Reach for `gl.message_raw` only when you need one of the extra fields. -## Time in a contract +## Time and Timestamps -Time inside the GenVM is **deterministic and pinned to the transaction's datetime**. Every validator re-executing the transaction sees the same value, so you can use it for storage, comparisons, and prompt context without breaking equivalence. +Time inside the GenVM is **deterministic and pinned to the transaction's timestamp**. Every validator re-executing the transaction sees the same value, so you can use it for storage, comparisons, and prompt context without breaking equivalence. The Python standard library's clock is wired to the transaction datetime — `datetime.now()`, `datetime.now(tz)`, and `time.time()` all return the same value across validators. +### Transaction Timestamp + +The transaction timestamp is exposed three ways. Use whichever fits: + +| Form | How | Use for | +|---|---|---| +| Unix seconds | `int(datetime.now(timezone.utc).timestamp())` | Arithmetic, expiries, deltas | +| Unix seconds (alt) | `int(time.time())` | Same — shorter | +| `datetime` object | `datetime.now(timezone.utc)` | Comparisons, formatting | +| ISO 8601 string | `datetime.now(timezone.utc).isoformat()` *or* `gl.message_raw['datetime']` | Storage, audit trails, prompts | + ### Common patterns **Unix timestamp for arithmetic:**