@fullonlabs/interop-js 4.0.3 → 4.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +88 -102
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,120 +1,106 @@
1
- # MultiChain Interoperability SDK
1
+ # FullOn Interop JavaScript SDK
2
2
 
3
-
4
- A wallet-agnostic TypeScript SDK for FullOn Network interoperability with
5
- Ethereum, BNB Smart Chain (BSC), Arbitrum, Solana, and Tron. Users can sign in
6
- and authorize transactions with a compatible third-party self-custodial wallet.
7
- Private keys stay in the wallet, and the SDK submits signed requests to FullOn
8
- for execution.
9
-
10
- ### Features
11
- - 🌐 **Multi-chain support**: integrated EVM-compatible chains (ETH/BSC/Arbitrum) and non-EVM chains (Solana/Tron)
12
- - 🔐 **Wallet connection**: support MetaMask/Phantom/TronLink and other mainstream wallets
13
- - 📦 **Out-of-the-box**: encapsulate chain interaction logic to simplify DApp development
3
+ [@fullonlabs/interop-js](https://www.npmjs.com/package/@fullonlabs/interop-js)
4
+ lets a DApp use a supported external wallet to bind and operate a FullOn
5
+ proxy account. The wallet signs the request locally. The SDK validates the
6
+ prepared message and submits it through a FullOn interop relayer.
14
7
 
15
8
  ## Install
16
9
 
17
- ```bash
10
+ ```sh
18
11
  npm install @fullonlabs/interop-js
19
- # or
20
- yarn add @fullonlabs/interop-js
21
12
  ```
22
13
 
23
- ## Currenly Supported Chain Types
24
- - `Ethereum`
25
- - `BSC`
26
- - `Arbitrum`
27
- - `Solana`
28
- - `Tron`
29
-
30
-
31
- ## FullOn interop relayer
32
-
33
- Set `chainApi` to the FullOn RPC endpoint and `proxyApi` to the base URL of a
34
- node or gateway exposing the interop plugin. The SDK supports both FullOn
35
- mainnet and testnet. Both endpoints must point to the same network. Use
36
- `https://m.flonscan.io` for both on mainnet or `https://t.flonscan.io` for both
37
- on testnet.
38
-
39
- Call `MultichainInteropJs.getRoutes()` to discover which binding and execution
40
- operations the selected relayer enables. Wallet connectivity and relayer route
41
- availability are independent. The SDK supports both `fullon-interop-v1` and
42
- `fullon-interop-v2`.
43
-
44
- The SDK prepares the request, checks the returned message against the target
45
- network and exact action bytes, signs with the wallet, and submits the result.
46
- `success:<transaction_id>` means the relayer accepted the transaction. Check
47
- the chain for finality. Login returns `pending:<transaction_id>` when the
48
- binding was accepted but its account is not visible yet.
49
-
50
- The built-in signers cover the configured EVM personal signing routes, Tron,
51
- Solana, and Statter. Supply `walletAdapters.btc` or `walletAdapters.ton` for
52
- Bitcoin or TON binding. Each adapter implements `connect()` and
53
- `sign(prepared)`, returning the ABI-formatted `signature` and the
54
- `wallet_fields` reported by the relayer for that operation. BTC and TON
55
- execution are unavailable with the current contract routes.
56
-
57
- ## Wallet login example
14
+ Node.js 20.19 or later is required when using the SDK in Node.js.
15
+
16
+ ## Configure FullOn and the relayer
17
+
18
+ Set `chainApi` to a FullOn RPC endpoint and `proxyApi` to the base URL of a
19
+ node or gateway exposing the interop plugin. Both endpoints must serve the
20
+ same network. The example uses the public testnet chain RPC and a placeholder
21
+ for an interop gateway. Replace the gateway URL with your deployment.
22
+
58
23
  ```js
59
- import MultichainInteropJs, { AccountInfo, ChainType } from '@fullonlabs/interop-js';
24
+ import MultichainInteropJs from '@fullonlabs/interop-js';
60
25
 
61
- // Initialize configuration (update chainApi URL when necessary)
62
26
  MultichainInteropJs.setConfig({
63
- chainApi: "https://m.flonscan.io",
64
- proxyApi: "https://your-interop-relayer.example",
65
- proxyContract: "interopproxy",
66
- ownerContract:"interopowner",
67
- defaultDelay: 3000,
27
+ chainApi: 'https://t.flonscan.io',
28
+ proxyApi: 'https://your-testnet-relayer.example',
29
+ proxyContract: 'interopproxy',
30
+ ownerContract: 'interopowner',
68
31
  });
69
32
 
70
- // Ethereum Login
71
- const ethLogin = async () => {
72
- try {
73
- const account: AccountInfo | string = await MultichainInteropJs.loginByChain('eth' as ChainType);
74
- if(typeof account === 'string'){
75
- console.log('errorMsg',account)
76
- }else{
77
- console.log('successObject',account)
78
- }
79
- } catch (error) {
80
- console.error('Login failed:', error);
81
- }
82
- };
83
-
84
- // Solana Login
85
- const solanaLogin = async () => {
86
- const account: AccountInfo | string = await MultichainInteropJs.loginByChain('solana' as ChainType);
87
- if(typeof account === 'string'){
88
- console.log('errorMsg',account)
89
- }else{
90
- console.log('Solana public key',account?.address)
91
- }
92
- };
33
+ const { routes, signing_protocol } = await MultichainInteropJs.getRoutes();
34
+ console.log(routes, signing_protocol);
35
+ ```
36
+
37
+ Use `https://m.flonscan.io` as the chain RPC for FullOn mainnet. For node
38
+ configuration, see the [relayer setup guide](https://github.com/fullon-labs/flon-core/blob/main/docs/01_node/03_plugins/interop_relayer_api_plugin/index.md).
39
+
40
+ The SDK supports `fullon-interop-v1` and `fullon-interop-v2`. The configured
41
+ relayer and deployed proxy must agree on the protocol. Use `getRoutes()` to
42
+ check each operation before presenting wallet options. A `null` operation
43
+ is unavailable on the selected relayer. If the response includes
44
+ `ready: false`, inspect its `readiness_code` before proceeding.
45
+
46
+ | Wallet | SDK chain argument | Contract operations |
47
+ | --- | --- | --- |
48
+ | Ethereum, BNB Smart Chain, Arbitrum | `eth`, `bsc`, `arbitrum` | Bind and execute |
49
+ | Tron, Solana, Statter | `tron`, `solana`, `statter` | Bind and execute |
50
+ | Bitcoin, TON | `btc`, `ton` | Bind only, with a wallet adapter |
51
+
52
+ The relayer reports Arbitrum as `arb`. The SDK maps the `arbitrum` argument
53
+ to that route. The routes advertised by the deployed relayer determine
54
+ actual availability.
55
+
56
+ Supply `walletAdapters.btc` or `walletAdapters.ton` for Bitcoin or TON
57
+ binding. An adapter implements `connect()`, which returns the external
58
+ address, and `sign(prepared)`, which returns the ABI-formatted `signature`
59
+ and any required `wallet_fields`. Wallet support alone does not enable a
60
+ route on the proxy contract.
61
+
62
+ ## Bind or look up a FullOn account
63
+
64
+ ```js
65
+ const login = await MultichainInteropJs.loginByChain('eth');
66
+
67
+ if (typeof login === 'string') {
68
+ // pending:<transaction_id> means the submitted binding is not visible yet.
69
+ console.log(login);
70
+ } else {
71
+ console.log(login.account, login.address);
72
+ }
93
73
  ```
94
74
 
75
+ For an unbound wallet, `loginByChain()` may request a wallet signature and
76
+ submit a new binding. When it returns a `pending:` result, check the
77
+ transaction and binding state before attempting another binding.
95
78
 
96
- ## Submit transaction example
79
+ ## Execute a FullOn action
80
+
81
+ The example assumes the wallet is already bound and the FullOn account has
82
+ enough FLON. Replace the recipient with a valid testnet account.
97
83
 
98
84
  ```js
99
- const sendTransaction = async () => {
100
- const result = await MultichainInteropJs.transactByChain(
101
- 'eth', // Chain Type
102
- '0x123...4ow', // User address
103
- [{ // Transaction parameters
104
- contract: 'abc.contract', //update contract accordingly
105
- action: 'transfer',
106
- data: {
107
- from: 'apl...eg',
108
- to: 'apl...ee',
109
- quantity: '1.0000 ETH'
110
- }
111
- }]
112
- );
113
-
114
- if (result.includes('success:')) {
115
- console.log('Transaction confirmed!');
116
- }else{
117
- console.log('errorMsg',result)
118
- }
119
- };
85
+ if (typeof login !== 'string') {
86
+ const result = await MultichainInteropJs.transactByChain('eth', login.address, [
87
+ {
88
+ contract: 'flon.token',
89
+ action: 'transfer',
90
+ data: {
91
+ from: login.account,
92
+ to: 'recipient',
93
+ quantity: '1.00000000 FLON',
94
+ memo: '',
95
+ },
96
+ },
97
+ ]);
98
+ console.log(result);
99
+ }
120
100
  ```
101
+
102
+ Action data can be JSON or ABI-encoded hex. The SDK checks that the prepared
103
+ request matches the configured chain and contracts, requested wallet route,
104
+ and exact action bytes before signing. A `success:<transaction_id>` result
105
+ means the relayer accepted the transaction. Use the chain to confirm
106
+ inclusion and finality.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "access": "public",
5
5
  "registry": "https://registry.npmjs.org/"
6
6
  },
7
- "version": "4.0.3",
7
+ "version": "4.0.5",
8
8
  "description": "A simple Web3 wallet connector supporting Ethereum, Solana, Tron, and Arbitrum.",
9
9
  "main": "./lib/index.js",
10
10
  "types": "./lib/index.d.ts",