near / near-token-rs

a small crate to work with NEAR token values ergonomically and efficiently

near-token

near-token is crate for work with tokens in near-protocol.

The crate includes NearToken type and constructors for converting data as NearToken and as u128 type values.

Examples

Basic

Add near-token to your dependencies:

cargo add near-token

Here is the basic usage of near-token crate:

use near_token::NearToken;

fn main() {
    const TEN_NEAR: NearToken = NearToken::from_near(10);

    assert_eq!(TEN_NEAR.to_string(), "10.00 NEAR");
    assert_eq!(TEN_NEAR.as_near(), 10);
    assert_eq!(TEN_NEAR.as_millinear(), 10000);
    assert_eq!(TEN_NEAR.as_yoctonear(), 10000000000000000000000000);

    let input_str = "0.123456 NEAR";
    let input_near: NearToken = input_str.parse().unwrap();
    assert_eq!(
        input_near,
        NearToken::from_yoctonear(123456000000000000000000)
    );

}

serde support

In order to use NearToken in serde-serializable structs, enable serde feature:

cargo add near-token --features serde

Here is the basic usage of near-token crate with serde:

// When `serde` feature is enabled, NearToken can be used in serde-serializable structs.
// NearToken will be serialized to a token-precision u128 value encoded as string.
#[derive(serde::Serialize)]
struct TransferDetails {
    amount: NearToken,
}

fn main() {
    const TEN_NEAR: NearToken = NearToken::from_near(10);

    let details = TransferDetails { amount: TEN_NEAR };
    assert_eq!(
        serde_json::to_string(&details).unwrap(),
        r#"{"amount":"10000000000000000000000000"}"#
    );
}

borsh support

In order to use NearToken in borsh-serializable structs, enable borsh feature:

cargo add near-token --features borsh

Here is the basic usage of near-token crate with borsh:

use borsh::{to_vec, BorshSerialize};
use near_token::NearToken;

#[derive(BorshSerialize)]
struct TransferDetails {
    amount: NearToken,
}

fn main() {
    const TEN_NEAR: NearToken = NearToken::from_near(10);

    let details = TransferDetails { amount: TEN_NEAR };
    assert_eq!(
        to_vec(&details).unwrap(),
        vec![0, 0, 0, 74, 72, 1, 20, 22, 149, 69, 8, 0, 0, 0, 0, 0]
    );
}

NearToken information

NEAR is used to price computation and storage on the NEAR infrastructure. The network charges transaction fees in NEAR to process changes and transactions.

License

This project is licensed under the MIT license and Apache-2.0 license.

near-token-rs's Issues

Security Policy violation SECURITY.md

This issue was automatically created by Allstar.

Security Policy Violation
Security policy not enabled.
A SECURITY.md file can give users information about what constitutes a vulnerability and how to report one securely so that information about a bug is not publicly visible. Examples of secure reporting methods include using an issue tracker with private issue support, or encrypted email with a published key.

To fix this, add a SECURITY.md file that explains how to handle vulnerabilities found in your repository. Go to https://github.com/near/near-token/security/policy to enable.

For more information, see https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository.

---

This issue will auto resolve when the policy is in compliance.

Issue created by Allstar. See https://github.com/ossf/allstar/ for more information. For questions specific to the repository, please contact the owner or maintainer.

Update the README with a nicer example

Current example is hard to read and it does not feature Display and FromStr features. Here is a draft of potentially good example:

const TEN_NEAR: NearToken = NearToken::from_near(10);

assert_eq!(TEN_NEAR.to_string(), "10.00 NEAR");
assert_eq!(TEN_NEAR.as_near(), 10);
// … as_millinear()
// … as_yoctonear()

let input_str= "0.123456 NEAR";
let input_near: NearToken = input_str.parse().unwrap();
assert_eq!(input_near, NearToken::from_yoctonear(…));

// … also, let’s feature serde and borsh serialization - add a struct with Serialize and BorshSerialize and serialize it

Fix bug in parsing 0.123456 NEAR

There is "attempt to multiply with overflow":