# limestone A Rust client SDK for Limestone [program](https://github.com/nifty-oss/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 clients interacting with the `limestone` program. To integrate `limestone` account derivation into your PDAs, you can use the library instead. ## Getting Started From your project folder: ```bash cargo add limestone-client ``` On your client, replace the use of `system_instruction::create_account` with `limestone::instructions::create_account`. The SDK provides helper to build the required `Instruction`: ```rust use limestone_client::{find_pda, instructions::CreateAccountBuilder}; // Creating an account to be used as a SPL Token 2022 mint let (pda, _) = find_pda(&payer, slot); let account_size = 200; // 200 bytes let create_ix = CreateAccountBuilder::new() .from(payer) .to(pda) .slot(slot) .lamports(rent.minimum_balance(account_size)) .space(account_size as u64) .owner(spl_token_2022::ID) .instruction(); ``` The arguments required to create an account are as follows: * `from` (signer: It is the funding account. * `to`: It is the account to be created (must be a PDA of `[base, slot]` derived from program_id). * `base` (signer, optional): Optional signer for the account derivation (it default to `from` 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`). * `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`: Program that will own the new account. 💡 **Note:** When using the client on-chain, replace the `CreateAccountBuilder` for `CreateAccountCpiBuilder`. ## 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 needs be added when closing an account to prevent recreation. 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.