diff --git a/Cargo.toml b/Cargo.toml index aa2e098..d2a15b8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,13 +1,12 @@ [workspace] - +resolver = "2" members = [ "near-providers", "near-transactions", - "near-api", + "near-api-lib", "near-accounts" ] - exclude = ["examples/"] [workspace.package] -version = "0.0.1" \ No newline at end of file +version = "0.1.0-alpha" \ No newline at end of file diff --git a/README.md b/README.md index e2457b8..1b939b1 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,126 @@ -# NEAR Rust API -Rust library to interact with NEAR Protocol via RPC API. Inspired by [NEAR API JS](https://github.com/near/near-api-js) +# near-api-lib + +The NEAR API library is a comprehensive Rust library designed to simplify the development of applications on the NEAR blockchain. It provides developers with essential tools and abstractions for account management, transaction building and signing, querying the blockchain state, and performing cryptographic operations, all from the comfort of Rust. + +## Features +- Account Management: Easily manage NEAR accounts, allowing for the creation of new accounts, key management, and account deletion. +- Transaction Building and Signing: Utilize a builder pattern for constructing and signing transactions with support for various actions. +- Blockchain Interaction: Communicate with the NEAR blockchain using the provided JSON RPC provider to query data or send transactions. +- Cryptographic Utilities: Access cryptographic functions for key generation, signing, and verification. (Rexport for easy access to existing `near-crypto` crate.) +- NEAR Blockchain Primitives: Work directly with NEAR blockchain primitives for low-level operations. (Rexport for easy access to existing `near-primitives` crate.) + + +## Getting Started +Add the following to your Cargo.toml file: +```toml +[dependencies] +near-api-lib = "0.1.0-alpha" +``` +### Usage +```rust +use near_api_lib::primitives::types::{AccountId, Balance, Gas}; +use near_api_lib::Account; +use near_api_lib::InMemorySigner; +use near_api_lib::JsonRpcProvider; + +use serde_json::json; +use std::sync::Arc; + +mod utils; + +#[tokio::main] +async fn main() -> Result<(), Box> { + +env_logger::init(); +let signer_account_id: AccountId = utils::input("Enter the signer Account ID: ")?.parse()?; +let signer_secret_key = utils::input("Enter the signer's private key: ")?.parse()?; +//To-do, implement account exist check. +let new_account_id: AccountId = utils::input("Enter new account name: ")?.parse()?; +let signer = InMemorySigner::from_secret_key(signer_account_id.clone(), signer_secret_key); + + +let gas: Gas = 100_000_000_000_000; // Example amount in yoctoNEAR +// Amount to transfer to the new account +let amount: Balance = 10_000_000_000_000_000_000_000; // Example amount in yoctoNEAR + + +let new_secret_key = near_crypto::SecretKey::from_random(near_crypto::KeyType::ED25519); +let provider = Arc::new(JsonRpcProvider::new("https://rpc.testnet.near.org")); +let signer = Arc::new(signer); + + + +let account = Account::new(signer_account_id, signer, provider); +let contract_id: AccountId = "testnet".parse::()?; +let method_name = "create_account".to_string(); + +let args_json = json!({ +"new_account_id": new_account_id, +"new_public_key": new_secret_key.public_key() +}); + +let result = account +.function_call(contract_id, method_name, args_json, gas, amount) +.await; + + +println!("Response: {:#?}", result); +println!("New Account ID: {}", new_account_id); +println!("Secret Key: {}", new_secret_key); + +Ok(()) +} +``` + +### Examples + +The crate includes examples that demonstrate how to use various features. To run an example, use the following command: +`cargo run --example ` + +For instance, to test the `create_account` function: +`cargo run --example create_account` + + + +## Contributing + +We welcome contributions to the `near-api-lib` crate! Please feel free to submit pull requests or open issues to suggest improvements or add new features. ## Disclaimer + ### General Use The near-api-rs is provided "as is" and "as available," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors, contributors, or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software. + ### Liability The creators of near-api-rs shall not be held liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. + ### No Warranty By using near-api-rs, you acknowledge and agree that the use of the software is entirely at your own risk. The software is provided "as is" and without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. + ### Accuracy and Reliability The authors and contributors to near-api-rs make no warranty that: 1. The software will meet your requirements or expectations. 2. The software will be uninterrupted, timely, secure, or error-free. 3. The results obtained from the use of the software will be accurate or reliable. 4. Any errors in the software will be corrected. + ### Responsibility It is your responsibility to ensure that your use of near-api-rs complies with all applicable laws and regulations, and to decide whether the software is suitable for your intended use. The authors and contributors assume no responsibility for your use of the software. + ### Modifications -The authors and contributors reserve the right to modify this disclaimer at any time, and such modifications shall be effective immediately upon posting of the modified disclaimer. Your continued use of near-api-rs shall be deemed your conclusive acceptance of the modified disclaimer. +The authors and contributors reserve the right to modify this disclaimer at any time, and such modifications shall be effective immediately upon posting of the modified disclaimer. Your continued use of near-api-rs shall be deemed your conclusive acceptance of the modified disclaimer. \ No newline at end of file diff --git a/near-accounts/Cargo.toml b/near-accounts/Cargo.toml index ad578f4..3e5a59b 100644 --- a/near-accounts/Cargo.toml +++ b/near-accounts/Cargo.toml @@ -2,11 +2,13 @@ name = "near-accounts" version = "0.1.0-alpha" edition = "2021" +description = "Simplify interaction with NEAR Protocol accounts. High-level abstractions for managing accounts, deploying contracts, and executing transactions on the NEAR blockchain." +license = "MIT OR Apache-2.0" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -near-crypto = "0.20.0" +near-crypto = "0.20.1" near-primitives = "0.20.1" near-providers = {path ="../near-providers"} near-transactions = {path ="../near-transactions"} diff --git a/near-accounts/examples/create_account.rs b/near-accounts/examples/create_account.rs index f9ae705..ddc6ba0 100644 --- a/near-accounts/examples/create_account.rs +++ b/near-accounts/examples/create_account.rs @@ -35,12 +35,9 @@ async fn main() -> Result<(), Box> { "new_account_id": new_account_id, "new_public_key": new_secret_key.public_key() }); - // Serialize the JSON to a Vec - // .into will convert it into Value type. - let args = serde_json::to_vec(&args_json)?.into(); let result = account - .function_call(contract_id, method_name, args, gas, amount) + .function_call(contract_id, method_name, args_json, gas, amount) .await; println!("response: {:#?}", result); diff --git a/near-accounts/examples/function_call.rs b/near-accounts/examples/function_call.rs index 2634316..4a98071 100644 --- a/near-accounts/examples/function_call.rs +++ b/near-accounts/examples/function_call.rs @@ -26,8 +26,6 @@ async fn main() -> Result<(), Box> { let method_name = "set_status".to_string(); let args_json = json!({"message": "working1"}); - // Serialize the JSON to a Vec - //let args = serde_json::to_vec(&args_json)?; let result = account .function_call(contract_id, method_name, args_json, gas, 0) diff --git a/near-accounts/examples/view_function.rs b/near-accounts/examples/view_function.rs index c18160a..b58f60a 100644 --- a/near-accounts/examples/view_function.rs +++ b/near-accounts/examples/view_function.rs @@ -22,10 +22,8 @@ async fn main() -> Result<(), Box> { let args_json = json!({"account_id": "contract.near-api-rs.testnet"}); let method_name = "get_status".to_string(); - let args_vec = serde_json::to_vec(&args_json)?.into(); - let result = account - .view_function(contract_id, method_name, args_vec) + .view_function(contract_id, method_name, args_json) .await; println!("response: {:#?}", result); diff --git a/near-accounts/src/accounts.rs b/near-accounts/src/accounts.rs index 3da663e..f77f381 100644 --- a/near-accounts/src/accounts.rs +++ b/near-accounts/src/accounts.rs @@ -6,7 +6,7 @@ use crate::access_keys::{full_access_key, function_call_access_key}; use near_crypto::{PublicKey, Signer}; use near_primitives::account::AccessKey; -use near_primitives::types::{AccountId, Balance, BlockReference, Finality, FunctionArgs, Gas}; +use near_primitives::types::{AccountId, Balance, BlockReference, Finality, Gas}; use near_primitives::views::{FinalExecutionOutcomeView, QueryRequest}; use near_providers::types::query::{QueryResponseKind, RpcQueryResponse}; use near_providers::Provider; @@ -351,12 +351,14 @@ impl Account { &self, contract_id: AccountId, method_name: String, - args: FunctionArgs, + args: Value, ) -> Result> { + let args_vec = serde_json::to_vec(&args)?.into(); + let query_request = QueryRequest::CallFunction { account_id: contract_id.clone(), method_name: method_name.clone(), - args: args.clone(), + args: args_vec, }; // Send the query to the NEAR blockchain diff --git a/near-accounts/src/lib.rs b/near-accounts/src/lib.rs index 91dbdf9..790c1d8 100644 --- a/near-accounts/src/lib.rs +++ b/near-accounts/src/lib.rs @@ -62,9 +62,6 @@ //! let method_name = "set_status".to_string(); //! let args_json = json!({"message": "working1"}); -//! // Serialize the JSON to a Vec -//! //let args = serde_json::to_vec(&args_json)?; - //! let result = account //! .function_call(contract_id, method_name, args_json, gas, 0) //! .await; diff --git a/near-api/Cargo.toml b/near-api-lib/Cargo.toml similarity index 61% rename from near-api/Cargo.toml rename to near-api-lib/Cargo.toml index 1a52fc7..e355a2e 100644 --- a/near-api/Cargo.toml +++ b/near-api-lib/Cargo.toml @@ -1,14 +1,16 @@ [package] -name = "near-api" +name = "near-api-lib" version = "0.1.0-alpha" edition = "2021" +description = "A Rust library for seamless NEAR blockchain development, offering tools for account management, transaction operations, and blockchain queries." +license = "MIT OR Apache-2.0" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] near-accounts = {path ="../near-accounts"} near-providers = {path ="../near-providers"} -near-crypto = "0.20.0" +near-crypto = "0.20.1" near-primitives = "0.20.1" tokio = { version = "1", features = ["full"] } serde_json = "1.0.85" diff --git a/near-api-lib/README.md b/near-api-lib/README.md new file mode 100644 index 0000000..170a374 --- /dev/null +++ b/near-api-lib/README.md @@ -0,0 +1,108 @@ + +# near-api-lib + +The NEAR API library is a comprehensive Rust library designed to simplify the development of applications on the NEAR blockchain. It provides developers with essential tools and abstractions for account management, transaction building and signing, querying the blockchain state, and performing cryptographic operations, all from the comfort of Rust. + + +## Features + +- Account Management: Easily manage NEAR accounts, allowing for the creation of new accounts, key management, and account deletion. + +- Transaction Building and Signing: Utilize a builder pattern for constructing and signing transactions with support for various actions. + +- Blockchain Interaction: Communicate with the NEAR blockchain using the provided JSON RPC provider to query data or send transactions. + +- Cryptographic Utilities: Access cryptographic functions for key generation, signing, and verification. (Rexport for easy access to existing `near-crypto` crate.) + +- NEAR Blockchain Primitives: Work directly with NEAR blockchain primitives for low-level operations. (Rexport for easy access to existing `near-primitives` crate.) + + + + +## Getting Started + + + +Add the following to your Cargo.toml file: + + + +```toml +[dependencies] +near-api-lib = "0.1.0-alpha" +``` + + + +### Usage + + + +```rust +use near_api_lib::primitives::types::{AccountId, Balance, Gas}; +use near_api_lib::Account; +use near_api_lib::InMemorySigner; +use near_api_lib::JsonRpcProvider; + +use serde_json::json; +use std::sync::Arc; + +mod utils; + +#[tokio::main] +async fn main() -> Result<(), Box> { + +env_logger::init(); +let signer_account_id: AccountId = utils::input("Enter the signer Account ID: ")?.parse()?; +let signer_secret_key = utils::input("Enter the signer's private key: ")?.parse()?; +//To-do, implement account exist check. +let new_account_id: AccountId = utils::input("Enter new account name: ")?.parse()?; +let signer = InMemorySigner::from_secret_key(signer_account_id.clone(), signer_secret_key); + + +let gas: Gas = 100_000_000_000_000; // Example amount in yoctoNEAR +// Amount to transfer to the new account +let amount: Balance = 10_000_000_000_000_000_000_000; // Example amount in yoctoNEAR + + +let new_secret_key = near_crypto::SecretKey::from_random(near_crypto::KeyType::ED25519); +let provider = Arc::new(JsonRpcProvider::new("https://rpc.testnet.near.org")); +let signer = Arc::new(signer); + + + +let account = Account::new(signer_account_id, signer, provider); +let contract_id: AccountId = "testnet".parse::()?; +let method_name = "create_account".to_string(); + +let args_json = json!({ +"new_account_id": new_account_id, +"new_public_key": new_secret_key.public_key() +}); + +let result = account +.function_call(contract_id, method_name, args_json, gas, amount) +.await; + + +println!("Response: {:#?}", result); +println!("New Account ID: {}", new_account_id); +println!("Secret Key: {}", new_secret_key); + +Ok(()) +} +``` + +### Examples + +The crate includes examples that demonstrate how to use various features. To run an example, use the following command: +`cargo run --example ` + +For instance, to test the `create_account` function: +`cargo run --example create_account` + + + +## Contributing + +We welcome contributions to the `near-api-lib` crate! Please feel free to submit pull requests or open issues to suggest improvements or add new features. \ No newline at end of file diff --git a/near-api/examples/contract_change_method_commit.rs b/near-api-lib/examples/contract_change_method_commit.rs similarity index 86% rename from near-api/examples/contract_change_method_commit.rs rename to near-api-lib/examples/contract_change_method_commit.rs index 09dbfad..801057a 100644 --- a/near-api/examples/contract_change_method_commit.rs +++ b/near-api-lib/examples/contract_change_method_commit.rs @@ -1,13 +1,13 @@ -use near_api::primitives::transaction::{Action, FunctionCallAction, Transaction}; -use near_api::primitives::types::BlockReference; -use near_api::providers::jsonrpc_client::{methods, JsonRpcClient}; -use near_api::providers::types::query::QueryResponseKind; +use near_api_lib::primitives::transaction::{Action, FunctionCallAction, Transaction}; +use near_api_lib::primitives::types::BlockReference; +use near_api_lib::providers::jsonrpc_client::{methods, JsonRpcClient}; +use near_api_lib::providers::types::query::QueryResponseKind; -use near_api::JsonRpcProvider; +use near_api_lib::JsonRpcProvider; // items from traits can only be used if the trait is in scope // can we change it somehow with better crate design? -use near_api::providers::Provider; +use near_api_lib::providers::Provider; use serde_json::json; diff --git a/near-api/examples/create_account.rs b/near-api-lib/examples/create_account.rs similarity index 82% rename from near-api/examples/create_account.rs rename to near-api-lib/examples/create_account.rs index 8eb949c..62a0b76 100644 --- a/near-api/examples/create_account.rs +++ b/near-api-lib/examples/create_account.rs @@ -1,7 +1,7 @@ -use near_api::primitives::types::{AccountId, Balance, Gas}; -use near_api::Account; -use near_api::InMemorySigner; -use near_api::JsonRpcProvider; +use near_api_lib::primitives::types::{AccountId, Balance, Gas}; +use near_api_lib::Account; +use near_api_lib::InMemorySigner; +use near_api_lib::JsonRpcProvider; use serde_json::json; use std::sync::Arc; @@ -36,12 +36,9 @@ async fn main() -> Result<(), Box> { "new_account_id": new_account_id, "new_public_key": new_secret_key.public_key() }); - // Serialize the JSON to a Vec - // .into will convert it into Value type. - let args = serde_json::to_vec(&args_json)?.into(); let result = account - .function_call(contract_id, method_name, args, gas, amount) + .function_call(contract_id, method_name, args_json, gas, amount) .await; println!("response: {:#?}", result); diff --git a/near-api/examples/get_access_key.rs b/near-api-lib/examples/get_access_key.rs similarity index 75% rename from near-api/examples/get_access_key.rs rename to near-api-lib/examples/get_access_key.rs index 4648e35..92e6f44 100644 --- a/near-api/examples/get_access_key.rs +++ b/near-api-lib/examples/get_access_key.rs @@ -1,6 +1,6 @@ -use near_api::accounts::get_access_key; -use near_api::primitives::types::AccountId; -use near_api::JsonRpcProvider; +use near_api_lib::accounts::get_access_key; +use near_api_lib::primitives::types::AccountId; +use near_api_lib::JsonRpcProvider; use std::sync::Arc; #[tokio::main] diff --git a/near-api/examples/utils.rs b/near-api-lib/examples/utils.rs similarity index 100% rename from near-api/examples/utils.rs rename to near-api-lib/examples/utils.rs diff --git a/near-api/examples/view_state.rs b/near-api-lib/examples/view_state.rs similarity index 85% rename from near-api/examples/view_state.rs rename to near-api-lib/examples/view_state.rs index e8cb494..bd32ec3 100644 --- a/near-api/examples/view_state.rs +++ b/near-api-lib/examples/view_state.rs @@ -1,5 +1,5 @@ -use near_api::accounts::view_state; -use near_api::JsonRpcProvider; +use near_api_lib::accounts::view_state; +use near_api_lib::JsonRpcProvider; use near_primitives::types::AccountId; use std::sync::Arc; diff --git a/near-api/src/lib.rs b/near-api-lib/src/lib.rs similarity index 100% rename from near-api/src/lib.rs rename to near-api-lib/src/lib.rs diff --git a/near-api/README.md b/near-api/README.md deleted file mode 100644 index e69de29..0000000 diff --git a/near-transactions/Cargo.toml b/near-transactions/Cargo.toml index 1335505..94b00e2 100644 --- a/near-transactions/Cargo.toml +++ b/near-transactions/Cargo.toml @@ -2,6 +2,8 @@ name = "near-transactions" version = "0.1.0-alpha" edition = "2021" +description = "High-level abstractions to facilitate the creation, manipulation, and signing of transactions on the NEAR blockchain." +license = "MIT OR Apache-2.0" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html