Timestamp

As a part of the Nostr protocol, events include a created_at field which contains the UNIX timestamp (in seconds) when the event was created. Note that this field can be useful in conjunction with the since and until properties of filters (see Filters section) to help clients surface recent/relevant content.

The Timestamp struct is responsible for handling the creation and/or parsing of timestamp objects. This section also covers the custom_created_at() method from the EventBuilder struct and the expiration tag used in functions like gift_wrap().

Creating, Parsing and Presenting Timestamps

Rust

TODO

Python

The Timestamp class is used to instantiate a timestamp object and the now() method can be used to populate this with the current UNIX timestamp. The to_human_datetime() and as_secs() methods can be used to present the timestamp data as a human-readable string or, UNIX integer timestamp in seconds, respectively.

    print("  Simple timestamp (now):")
    timestamp = Timestamp.now()
    print(f"     As str: {timestamp.to_human_datetime()}")
    print(f"     As int: {timestamp.as_secs()}")

To parse timestamps from integer values the from_secs() method can be used. 

    print("  Parse timestamp (sec):")
    timestamp = Timestamp.from_secs(1718737479)
    print(f"     {timestamp.to_human_datetime()}")
JavaScript

TODO

Kotlin

TODO

Swift

TODO

Created_at and Expiration

Rust

TODO

Python

When building Event objects it is possible to utilize the custom_created_at() method in conjunction with an instance of the Timestamp class to manually set the created_at field for events. When parsing events, the create_at() method is used to extract this timestamp information.

    print("  Created at timestamp:")
    event = EventBuilder(Kind(1), "This is some event text.", []).custom_created_at(timestamp).to_event(alice_keys)
    print(f"     Created at: {event.created_at().to_human_datetime()}")

To create expiration tags for inclusion within events the Tag class is used along with the expiration() method.

    print("  Timestamp Tag:")
    tag = Tag.expiration(timestamp)
    print(f"     Tag: {tag.as_standardized()}")

This example shows how the expiration tag can be set directly during the calling of the gift_wrap() function. 

    print("  Expiration timestamp:")
    gw = gift_wrap(alice_keys, bob_keys.public_key(),
                   EventBuilder.text_note("Test", []).to_unsigned_event(alice_keys.public_key()), Timestamp.now())
    print(f"     Expiration: {gw.expiration().to_human_datetime()}")
JavaScript

TODO

Kotlin

TODO

Swift

TODO