Jovay Interaction Skill

Description

This skill enables interaction with Jovay, a secure, open, and modular Layer2 EVM blockchain. It uses the jovay-cli tool to perform wallet management, token transfers, smart contract interactions, and network configuration.

Prerequisites

• Node.js v20+
• jovay-cli installed (npm install -g @jovaylabs/jovay-cli)
• Configured wallet with private key
• Network configured (testnet or mainnet)

Network information (official)

Canonical RPC URLs, chain IDs, explorers, and all bridge contract addresses (ETH and ERC-20) are maintained in the Jovay documentation:

• Network Information

Quick reference — ETH bridge (same values as jovay-cli src/common/bridge.ts):

ERC-20 bridge addresses are listed only in the doc above; use jovay contract with those addresses for token approvals and transfers.

Instructions

When the user wants to interact with Jovay blockchain, follow these patterns:

Initial Setup

Note: Initialization is only required once after installation. You can verify if initialization is complete by running jovay network get. If it returns network configuration info, initialization has already been done.

1. Initialize CLI: jovay init
2. Check network: jovay network get
3. Switch network: jovay network switch --network testnet|mainnet
4. Configure wallet: jovay wallet set --sk <private-key> [--enc]

Wallet Operations

Set Wallet

Configure wallet with private key.

jovay wallet set --sk <private-key> [--enc] [--enc-key <password>]

Options:

• --sk, --secret-key <key>: Private key (64 hex characters, with or without 0x prefix)
• --enc: Enable encryption with auto-generated key (save the key!)
• --enc-key <password>: Custom encryption password (auto-enables encryption)
• --origin-enc-key <key>: Current encryption key (required when changing encrypted wallet)

Get Address

jovay wallet address

Check Balance

jovay wallet balance [options]

Options:

• --address <0x string>: Address to query (defaults to wallet address)
• --token <0x string>: ERC20 token address (omit for native ETH)
• --l1: Query on Ethereum instead of Jovay
• --rpc <url>: Custom RPC endpoint
• --block <number>: Query at specific block height

Airdrop (Testnet Only)

Request 0.001 Jovay Sepolia ETH (once per 24 hours).

jovay wallet airdrop

Transfer

jovay wallet transfer --amount <wei> --to <address> [options]

Options:

• --amount <bigint>: Amount in smallest unit (Wei) - required
• --to <0x string>: Recipient address - required
• --token <0x string>: ERC20 token address (omit for native ETH)
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --l1: Transfer on Ethereum instead of Jovay
• --rpc <url>: Custom RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

Approve

jovay wallet approve --amount <amount> --to <spender> --token <address> [options]

Options:

• --amount <bigint>: Allowance amount in smallest unit - required
• --to <0x string>: Spender address - required
• --token <0x string>: ERC20 token address - required
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --l1: Approve on Ethereum instead of Jovay
• --rpc <url>: Custom RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

Bridge Operations

Deposit ETH (L1 → L2)

Bridge ETH from Ethereum to Jovay.

jovay bridge deposit --amount <wei> --to <l2-address> [options]

Options:

• --amount <bigint>: Amount in Wei to deposit - required
• --to <0x string>: Recipient address on Jovay (L2) - required
• --gas-limit <bigint>: Gas limit reserved for the L2 finalize-deposit step (default: 200000). It must be ≥ the gas the bridge needs on Jovay; if it is too low, the L1 transaction reverts with gas limit must be bigger than or equal to the tx_fee of finalize deposit on Jovay. On Jovay Sepolia testnet, 500000 is often required. A larger limit increases msg.value (see note below).
• --data <hex>: Optional extra data (default: 0x)
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --rpc <url>: Custom L1 RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

Note: The bridge requires msg.value = amount + gasLimit × L2 gas price. The CLI computes this from your configured L2 RPC and sends the correct msg.value automatically. Your L1 wallet must hold enough for that msg.value plus L1 gas. After the L1 transaction is finalized, the bridge relayer credits funds on L2.

Withdraw ETH (L2 → L1)

Bridge ETH from Jovay back to Ethereum. This is a two-step process.

jovay bridge withdraw --amount <wei> --to <l1-address> [options]

Options:

• --amount <bigint>: Amount in Wei to withdraw - required
• --to <0x string>: Recipient address on Ethereum (L1) - required
• --gas-limit <bigint>: Gas limit for the L1 finalization transaction (default: 200000)
• --data <hex>: Optional extra data (default: 0x)
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --rpc <url>: Custom L2 RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

Note: The bridge requires msg.value = amount + gasLimit × L1 gas price. The CLI computes this from your configured L1 RPC. Your L2 wallet must hold enough for that msg.value plus L2 gas. After the L2 transaction is confirmed, wait for the batch to be finalized on L1 (up to 1 hour). Then run jovay bridge finalize-withdraw with the proof data from the Jovay Explorer.

Finalize Withdraw (L1 - Step 2)

After the L2 withdrawal batch is finalized, claim your funds on Ethereum.

jovay bridge finalize-withdraw --amount <wei> --nonce <nonce> --msg <hex> --batch-index <index> --proof <hex> [options]

Options:

• --amount <bigint>: The exact amount of ETH withdrawn on L2 (Wei) - required
• --nonce <bigint>: Nonce of the cross-chain message (from SentMsg event log) - required
• --msg <hex>: Original message from the SentMsg event log (hex, 0x-prefixed) - required
• --batch-index <bigint>: Batch index containing the L2 withdrawal tx - required
• --proof <hex>: SPV merkle proof from the Jovay Explorer transaction page - required
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --rpc <url>: Custom L1 RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

How to get proof data: Go to your L2 withdrawal transaction on the Jovay Explorer. Find the SentMsg event to get the nonce and msg. Click the block number to find the batchIndex. Copy the "Proof" hex string for --proof.

Claim Deposit (L2 - Manual)

If the automatic L1 → L2 deposit relay fails, manually claim on L2.

jovay bridge claim-deposit --msg <hex> [options]

Options:

• --msg <hex>: Original message data from the DepositETH event log (hex, 0x-prefixed) - required
• --sk <key>: Override wallet private key
• --enc-key <password>: Encryption key for encrypted wallet
• --rpc <url>: Custom L2 RPC endpoint
• --broadcast: Send transaction (without this, only outputs signed data)

Contract Interactions

Read Contract (call)

Read data from a contract without sending a transaction.

With ABI file:

jovay contract call --contract <address> --method <name> --abi <file> --args '<json-args>'

Without ABI (manual type definition):

jovay contract call --contract <address> --method <name> --inputs <types> --outputs <types> --args '<json-args>'

Common options:

• --contract <address>: Contract address (required)
• --method <name>: Method name to call (required)
• --abi <file>: Path to ABI JSON file
• --inputs <types>: Input parameter types (e.g., address,uint256[])
• --outputs <types>: Output parameter types (e.g., string,(address,uint256))
• --args '<json>': Arguments as JSON array string
• --l1: Call on Ethereum instead of Jovay
• --rpc <url>: Custom RPC endpoint
• --dry-run: Output encoded data without calling

Write Contract (write)

Send a transaction to modify contract state.

With ABI file:

jovay contract write --contract <address> --method <name> --abi <file> --args '<json-args>' --broadcast

Without ABI:

jovay contract write --contract <address> --method <name> --inputs <types> --args '<json-args>' --broadcast

Common options:

• --contract <address>: Contract address (required)
• --method <name>: Method name to call (required)
• --abi <file>: Path to ABI JSON file
• --inputs <types>: Input parameter types
• --args '<json>': Arguments as JSON array string
• --value <wei>: Native token to send (for payable functions)
• --broadcast: Send transaction to network (required to execute)
• --sk <key>: Override wallet private key
• --enc-key <key>: Encryption key for encrypted wallet
• --l1: Write on Ethereum instead of Jovay
• --rpc <url>: Custom RPC endpoint

Type Definition Examples

Args Format Examples

Transaction Operations

Get Transaction Info

jovay transaction info --tx <hash> [options]

Options:

• --tx, --transaction <hash>: Transaction hash - required
• --raw: Display full raw JSON response instead of formatted summary
• --abi <file>: ABI file path to decode event logs
• --rpc <url>: Custom RPC endpoint
• --l1: Query on Ethereum instead of Jovay

Send Raw Transaction

jovay transaction send --raw-tx <signed-tx> [options]

Options:

• --raw-tx <string>: Signed raw transaction data - required
• --rpc <url>: Custom RPC endpoint
• --l1: Send to Ethereum instead of Jovay

Network Configuration

Get Network Info

jovay network get

Displays current network configuration and wallet info.

Switch Network

jovay network switch --network <testnet|mainnet> [options]

Options:

• --network <string>: Target network - required (testnet or mainnet)
• --api-key <string>: ZAN API key for RPC endpoints
• --l1, --l1-rpc <url>: Custom Ethereum RPC endpoint
• --l2, --l2-rpc <url>: Custom Jovay RPC endpoint

Set Network Config

jovay network set [options]

Options:

• --api-key <string>: Update ZAN API key
• --l1, --l1-rpc <url>: Update Ethereum RPC endpoint
• --l2, --l2-rpc <url>: Update Jovay RPC endpoint

Examples

jovay wallet balance

For ERC20 token balance, use:

jovay wallet balance --token 0x<token-address>

</assistant_response>

jovay wallet transfer --amount 10000000000000000 --to 0x1234...abcd --broadcast

</assistant_response>

jovay contract call \
  --contract 0x<contract-address> \
  --method balanceOf \
  --inputs address \
  --outputs uint256 \
  --args '"0x<wallet-address>"'

</assistant_response>

jovay contract call \
  --contract 0x<contract-address> \
  --method getTokenInfo \
  --abi ./path/to/abi.json \
  --args '"0x<token-address>"'

</assistant_response>

jovay contract call \
  --contract 0x<contract-address> \
  --method processOrder \
  --inputs "address,(uint256,string)" \
  --outputs "bool" \
  --args '"0x<address>", [1000, "order-123"]'

</assistant_response>

jovay contract write \
  --contract 0x<token-address> \
  --method transfer \
  --inputs "address,uint256" \
  --args '"0x<recipient>", 1000000000000000000' \
  --broadcast

</assistant_response>

jovay contract write \
  --contract 0x<nft-address> \
  --method mint \
  --inputs "uint256" \
  --args '1' \
  --value 100000000000000000 \
  --broadcast

This sends 0.1 ETH (100000000000000000 Wei) to mint 1 NFT. </assistant_response>

jovay contract call \
  --contract 0x<contract-address> \
  --method approve \
  --inputs "address,uint256" \
  --args '"0x<spender>", 1000000' \
  --dry-run

This outputs the encoded function data that can be used in other tools or transactions. </assistant_response>

jovay contract call \
  --contract 0x<l1-contract-address> \
  --method balanceOf \
  --inputs address \
  --outputs uint256 \
  --args '"0x<wallet-address>"' \
  --l1

</assistant_response>

jovay contract write \
  --contract 0x<contract-address> \
  --method setApprovalForAll \
  --inputs "address,bool" \
  --args '"0x<operator>", true' \
  --enc-key "your-encryption-password" \
  --broadcast

</assistant_response>

First, ensure you're on testnet:

jovay network switch --network testnet

Then request airdrop:

jovay wallet airdrop

</assistant_response>

jovay bridge deposit --amount 100000000000000000 --to 0x<your-l2-address> --gas-limit 500000 --broadcast

</assistant_response>

Step 1 - Initiate withdrawal on L2:

jovay bridge withdraw --amount 50000000000000000 --to 0x<your-l1-address> --broadcast

After this transaction is confirmed, wait for the batch to be finalized on L1 (up to 1 hour). Then get the proof data from the Jovay Explorer and run step 2.

Step 2 - Finalize on L1:

jovay bridge finalize-withdraw \
  --amount 50000000000000000 \
  --nonce <nonce-from-SentMsg-event> \
  --msg <hex-message-from-SentMsg-event> \
  --batch-index <batch-index> \
  --proof <merkle-proof-hex> \
  --broadcast

</assistant_response>

jovay bridge claim-deposit --msg 0x<message-from-DepositETH-event> --broadcast

You can find the message data in the transaction details on an L1 block explorer (e.g., Etherscan). </assistant_response>

Important Notes

1. Amount units: All amounts must be in smallest unit (Wei for ETH, smallest decimal for tokens)
2. Broadcast flag: Use --broadcast to send transactions; without it, only signed data is output
3. L1 vs L2: Use --l1 flag to operate on Ethereum instead of Jovay
4. Encrypted wallet: Use --enc-key when wallet is encrypted
5. ABI files: Provide --abi for complex contract interactions, or use --inputs/--outputs for simple cases
6. Bridge deposit --gas-limit: If L1 deposit fails with finalize deposit on Jovay, increase --gas-limit (testnet often needs 500000 or more). This also increases msg.value on L1.