# limestone Limestone enables the creation short-lived program derived address (PDA) signers. These signers are used to create accounts which can be "safely" closed since the same account address signer cannot be recreated after a time period — `time` in this case measured in terms of slots. This feature is useful to avoid reusing an account for something completely different, which can create problems for applications and off-chain services that store any information about the account. Therefore, accounts can be closed, avoiding bloating account state, returning all rent funds and enabling the use of accounts to represent "ephemeral" concepts (e.g., receipts, tickets) without incurring unnecessary costs. > This crate is intended to be used by programs. To create an account from a client, consider using the `limestone` program. ## Getting Started From your project folder: ```bash cargo add limestone ``` On your program, replace the use of `system_instruction::create_account` with `limestone::create_account`: ```rust use limestone::{Arguments, create_account}; create_account( program_id, Arguments { from: ctx.accounts.from, to: ctx.accounts.to, lamports, space, owner: Some(system_program::ID), slot, }, )?; ``` The arguments for the `create_account` are as follows: * `program_id`: It is the address of your program (the account derivation will be done within the scope of the program). * `from` (signer, writable): It is the funding account. * `to` (writable): It is the account to be created (must be a PDA of `[from, slot]` derived from program_id). * `lamports`: The lamports to be transferred to the new account (must be at least the amount needed for the account to be rent-exempt). * `space`: The data size for the new account. * `owner`: Optinal program that will own the new account (it default to `program_id` if omitted). * `slot`: The slot number for the derivation (the slot needs to be within the valid range, i.e., not older than `current slot - TTL`). ### 💡 Important `create_account` uses the default `TTL` value of `150` slots. This is typically the number of slots that a `blockhash` is available and maximizes the chance of the account creation to succeed. You can use the `create_account_with_ttl` if you want to use a different `TTL` value – a lower `TTL` provides a shorter interval for the PDA signer to be available. At the same time, if your transaction is not executed within the `TTL` slots, it will fail. ## Limitation Although the use `TTL` defines a time period where the account creation is allowed — `150` slots is approximately 1 minute 19 seconds assuming `400`ms block times — it does not guarantee that the account is not closed and recreated between that interval. Additionally, it does not prevent an account being created, closed and recreated on the same transaction. For protocols that need such guarantee, an addional restriction should be added when closing an account that should not be recreated. The protocol should store the `slot` value used on the account derivation and validate that the account is being closed after `slot + TTL` — this will prevent the account recreation since the `slot` value will be too old to generate a PDA signer. Since a slot value is part of the derivation of the account, it cannot be easily used in scenarios where durable nonces are required to build transactions. It is very likely that the slot value will be invalid when the transaction is signed at a point in the future. This limitation is not due to the approach of using a PDA signer — it arises from the fact that the slot expires in the same way that a blockhash expires. The alternative in this case is to use an approach where the slot in the derivation is replaced by the nonce value, which will provide a similar guarantee that a derivation is only valid for a particular nonce value. ## License Copyright (c) 2024 nifty-oss maintainers Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.