@xchainjs/xchain-radix 0.1.1

package/README.md

@@ -0,0 +1,213 @@
+# `@xchainjs/xchain-radix`
+
+Radix module for XChainJS clients
+
+## Modules
+
+- `client` - Custom client for communicating with the Radix Chain by using the [radix-engine-toolkit](https://github.com/radixdlt/typescript-radix-engine-toolkit/tree/main) and the [radix gateway api](https://radix-babylon-gateway-api.redoc.ly/)
+
+- `types` - Typescript type defintions used by the client on top of the types defined by the [Typescript Gateway API SDK](https://www.npmjs.com/package/@radixdlt/babylon-gateway-api-sdk)
+
+## Installation
+
+```
+yarn add @xchainjs/xchain-radix
+```
+
+## Fund an account in testnet
+
+```
+yarn fund account_address
+```
+
+## Examples
+
+### Creating a radix client
+
+```
+import { Network, XChainClientParams } from '@xchainjs/xchain-client'
+import { Client } from '@xchainjs/xchain-radix'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+const client = new Client(params, 'Ed25519')
+console.log(client.getAssetInfo())
+```
+
+### Creating a transaction
+
+There are two methods related to creating transactions: prepareTx and transfer
+The first one creates a raw unsigned transaction (it doesn't submit the transaction). The
+second one submits the transaction to the ledger
+
+#### prepareTx
+
+```
+import { Network, TxParams, XChainClientParams } from '@xchainjs/xchain-client'
+import { Client, XrdAssetStokenet } from '@xchainjs/xchain-radix'
+import { baseAmount } from '@xchainjs/xchain-util/lib'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+
+async function main() {
+  const client = new Client(params, 'Ed25519')
+
+  const txParams: TxParams = {
+    asset: XrdAssetStokenet,
+    amount: baseAmount(1),
+    recipient: 'account_tdx_2_129wjagjzxltd0clr3q4z7hqpw5cc7weh9trs4e9k3zfwqpj636e5zf',
+    memo: 'test',
+  }
+  const preparedTx = await client.prepareTx(txParams)
+  console.log(preparedTx)
+}
+
+main().catch(console.error)
+```
+
+#### transfer
+
+```
+import { Network, TxParams, XChainClientParams } from '@xchainjs/xchain-client'
+import { Client, XrdAssetStokenet } from '@xchainjs/xchain-radix'
+import { baseAmount } from '@xchainjs/xchain-util/lib'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+
+async function main() {
+  const client = new Client(params, 'Ed25519')
+
+  const txParams: TxParams = {
+    asset: XrdAssetStokenet,
+    amount: baseAmount(1),
+    recipient: 'account_tdx_2_129wjagjzxltd0clr3q4z7hqpw5cc7weh9trs4e9k3zfwqpj636e5zf',
+    memo: 'test',
+  }
+  const transactionId = await client.transfer(txParams)
+  console.log(transactionId)
+}
+
+main().catch(console.error)
+```
+
+### Getting a transaction data
+
+```
+import { Network, Tx, TxParams, XChainClientParams } from '@xchainjs/xchain-client/lib'
+import { Client } from '@xchainjs/xchain-radix'
+import { XrdAsset } from '@xchainjs/xchain-radix/src/const'
+import { baseAmount } from '@xchainjs/xchain-util'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Mainnet,
+  phrase: phrase,
+}
+const client = new Client(params, 'Ed25519')
+
+const txParams: TxParams = {
+  asset: XrdAsset,
+  amount: baseAmount(1000),
+  recipient: 'account_rdx169yt0y36etavnnxp4du5ekn7qq8thuls750q6frq5xw8gfq52dhxhg',
+}
+const transferTransaction = await radixClient.transfer(txParams)
+const transaction: Tx = await radixClient.getTransactionData(transferTransaction)
+console.log(transaction)
+```
+
+### Getting balances
+
+```
+import { Balance, Network, XChainClientParams } from '@xchainjs/xchain-client/lib'
+import { Client } from '@xchainjs/xchain-radix'
+import { Asset } from '@xchainjs/xchain-util/lib'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+const assets: Asset[] = [
+  {
+    symbol: 'resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd',
+    ticker: 'resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd',
+    chain: 'radix',
+    synth: false,
+  },
+]
+const balances: Balance[] = await radixClient.getBalance(
+  'account_rdx16x47guzq44lmplg0ykfn2eltwt5wweylpuupstsxnfm8lgva7tdg2w',
+  assets,
+)
+console.log(balances)
+```
+
+### Getting fees
+
+```
+import { Fees, Network, XChainClientParams } from '@xchainjs/xchain-client/lib'
+import { Client } from '@xchainjs/xchain-radix'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+const client = new Client(params, 'Ed25519')
+const fees: Fees = await radixClient.getFees()
+console.log(fees)
+```
+
+### Getting transactions history
+
+```
+import { Network, XChainClientParams } from '@xchainjs/xchain-client/lib'
+import { Client } from '@xchainjs/xchain-radix'
+
+const phrase = 'rural bright ball negative already grass good grant nation screen model pizza'
+const params: XChainClientParams = {
+  network: Network.Testnet,
+  phrase: phrase,
+  feeBounds: { lower: 1, upper: 5 },
+}
+const client = new Client(params, 'Ed25519')
+
+const transactionsHistoryParams = {
+  address: 'account_rdx169yt0y36etavnnxp4du5ekn7qq8thuls750q6frq5xw8gfq52dhxhg',
+  offset: 72533720,
+  limit: 200,
+  asset: 'resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd',
+}
+const txs = await (await radixClient.getTransactions(transactionsHistoryParams)).txs
+console.log(txs)
+```
+
+## Service providers
+
+This package uses the following service providers
+
+| Function                    | Service               | Notes                                                                             | Rate limits              |
+| --------------------------- | --------------------- | --------------------------------------------------------------------------------- | ------------------------ |
+| Balances                    | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/StateEntityDetails          | 1550 requests per minute |
+| Transaction history         | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/StreamTransactions          | 1550 requests per minute |
+| Transaction details by hash | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/TransactionCommittedDetails | 1550 requests per minute |
+| Fees                        | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/TransactionPreview          | 1550 requests per minute |
+| Transaction broadcast       | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/TransactionSubmit           | 1550 requests per minute |
+| Transfer                    | Radix Network Gateway | https://radix-babylon-gateway-api.redoc.ly/#operation/TransactionSubmit           | 1550 requests per minute |
+| Explorer                    | Dashboard             | https://dashboard.radixdlt.com/                                                   |                          |

package/lib/client.d.ts

@@ -0,0 +1,148 @@
+/// <reference types="node" />
+import { GatewayApiClient, TransactionSubmitResponse } from '@radixdlt/babylon-gateway-api-sdk';
+import { Curve, Intent, NotarizedTransaction, PrivateKey, PublicKey, TransactionHash } from '@radixdlt/radix-engine-toolkit';
+import { AssetInfo, Balance, BaseXChainClient, Fees, Network, PreparedTx, Tx, TxHistoryParams, TxParams, TxsPage, XChainClientParams } from '@xchainjs/xchain-client';
+import { Address, Asset } from '@xchainjs/xchain-util';
+/**
+ * The main client for the Radix network which is then wrapped by the {Client} adapting it to have
+ * a {BaseXChainClient} interface.
+ */
+export declare class RadixSpecificClient {
+    private innerNetwork;
+    private innerGatewayClient;
+    constructor(networkId: number);
+    set networkId(networkId: number);
+    get networkId(): number;
+    get gatewayClient(): GatewayApiClient;
+    currentEpoch(): Promise<number>;
+    currentStateVersion(): Promise<number>;
+    fetchBalances(address: string): Promise<Balance[]>;
+    fetchNFTBalances(address: string): Promise<Balance[]>;
+    private convertResourcesToBalances;
+    private fetchNonFungibleResources;
+    private fetchFungibleResources;
+    constructSimpleTransferIntent(from: string, to: string, resourceAddress: string, amount: number, notaryPublicKey: PublicKey, message?: string): Promise<{
+        intent: Intent;
+        fees: number;
+    }>;
+    submitTransaction(notarizedTransaction: NotarizedTransaction): Promise<[TransactionSubmitResponse, TransactionHash]>;
+    private static createGatewayClient;
+    private static simpleTransferManifest;
+    private constructIntent;
+    private previewIntent;
+    private static retPublicKeyToGatewayPublicKey;
+}
+/**
+ * Custom Radix client
+ */
+export default class Client extends BaseXChainClient {
+    private radixSpecificClient;
+    private curve;
+    constructor({ network, phrase, rootDerivationPaths, feeBounds, curve, }: XChainClientParams & {
+        curve?: Curve;
+    });
+    get radixClient(): RadixSpecificClient;
+    setNetwork(network: Network): void;
+    /**
+     * Get an estimated fee for a test transaction that involves sending
+     * XRD from one account to another
+     *
+     * @returns {Fee} An estimated fee
+     */
+    getFees(): Promise<Fees>;
+    getRadixNetwork(): number;
+    getPrivateKey(index: number): Buffer;
+    getRadixPrivateKey(index: number): PrivateKey;
+    /**
+     * Get the address for a given account.
+     * @deprecated Use getAddressAsync instead.
+     */
+    getAddress(): string;
+    /**
+     * Get the current address asynchronously for a given account.
+     * @returns {Address} A promise resolving to the current address.
+     * A phrase is needed to create a wallet and to derive an address from it.
+     */
+    getAddressAsync(index?: number): Promise<string>;
+    /**
+     * Get the explorer URL based on the network.
+     *
+     * @returns {string} The explorer URL based on the network.
+     */
+    getExplorerUrl(): string;
+    /**
+     * Get the explorer URL for a given account address based on the network.
+     * @param {Address} address The address to generate the explorer URL for.
+     * @returns {string} The explorer URL for the given address.
+     */
+    getExplorerAddressUrl(address: Address): string;
+    /**
+     * Get the explorer URL for a given transaction ID based on the network.
+     * @param {string} txID The transaction ID to generate the explorer URL for.
+     * @returns {string} The explorer URL for the given transaction ID.
+     */
+    getExplorerTxUrl(txID: string): string;
+    /**
+     *  Validate the given address.
+     * @param {Address} address The address to validate.
+     * @returns {boolean} `true` if the address is valid, `false` otherwise.
+     */
+    validateAddressAsync(address: string): Promise<boolean>;
+    validateAddress(address: string): boolean;
+    /**
+     * Retrieves the balances of a given address.
+     * @param {Address} address - The address to retrieve the balance for.
+     * @param {Asset[]} assets - Assets to retrieve the balance for (optional).
+     * @returns {Promise<Balance[]>} An array containing the balance of the address.
+     */
+    getBalance(address: Address, assets?: Asset[]): Promise<Balance[]>;
+    /**
+     * Get transaction history of a given address with pagination options.
+     * @param {TxHistoryParams} params The options to get transaction history. (optional)
+     * @returns {TxsPage} The transaction history.
+     */
+    getTransactions(params: TxHistoryParams): Promise<TxsPage>;
+    /**
+     * Get the transaction details of a given transaction id.
+     * This method uses LTSRadixEngineToolkit.Transaction.summarizeTransaction
+     * to convert a transaction hex to a transaction summary. If the transaction was not built with
+     * the SimpleTransactionBuilder, the method will fail to get the transaction data
+     * @param {string} txId The transaction id.
+     * @returns {Tx} The transaction details of the given transaction id.
+     */
+    getTransactionData(txId: string): Promise<Tx>;
+    /**
+     * Helper function to convert a transaction in hex, returned by the gateway to a Tx type
+     * @param transaction_hex - The raw_hex returned by the gateway for a transaction id
+     * @param confirmed_at - The confirmed_at date for the transaction
+     * @param intent_hash - The transaction intent hash
+     * @returns a transaction in Tx type
+     */
+    convertTransactionFromHex(transaction_hex: string, intent_hash: string, confirmed_at: Date): Promise<Tx>;
+    /**
+     * Creates a transaction using the SimpleTransactionBuilder, signs it with the
+     * private key and returns the signed hex
+     * @param params - The transactions params
+     * @returns A signed transaction hex
+     */
+    transfer(params: TxParams): Promise<string>;
+    /**
+     * Submits a transaction
+     * @param txHex - The transaction hex build with the transfer method
+     * @returns - The response from the gateway
+     */
+    broadcastTx(txHex: string): Promise<string>;
+    /**
+     * Prepares a transaction to be used by the transfer method
+     * It will include a non signed transaction
+     * @param params - The transaction params
+     * @returns a PreparedTx
+     */
+    prepareTx(params: TxParams): Promise<PreparedTx>;
+    /**
+     * Get asset information.
+     * @returns Asset information.
+     */
+    getAssetInfo(): AssetInfo;
+}
+export { Client };

package/lib/const.d.ts

@@ -0,0 +1,32 @@
+import { RootDerivationPaths } from '@xchainjs/xchain-client';
+import { Asset } from '@xchainjs/xchain-util';
+/**
+ * Chain identifier for Radix.
+ * This constant represents the identifier for the Radix Chain.
+ */
+export declare const RadixChain: "RADIX";
+export declare const MAINNET_GATEWAY_URL = "https://mainnet.radixdlt.com";
+export declare const STOKENET_GATEWAY_URL = "https://stokenet.radixdlt.com";
+export declare const XRD_DECIMAL = 18;
+export declare const XrdAssetMainnet: Asset;
+export declare const XrdAssetStokenet: Asset;
+export declare const xrdRootDerivationPaths: RootDerivationPaths;
+export declare const bech32Networks: {
+    [key: number]: string;
+};
+export declare const bech32Lengths: {
+    [key: number]: number;
+};
+interface FeesEstimationParams {
+    from: string;
+    to: string;
+    resourceAddress: string;
+    publicKey: string;
+}
+export declare const feesEstimationPublicKeys: {
+    [networkId: number]: FeesEstimationParams;
+};
+export declare const assets: {
+    [networkId: number]: Asset;
+};
+export {};

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { Client } from './client';
+export * from './const';
+export * from './types/radix';