Create Your First Record

Learning Objectives

By the end of this step, you'll:

Understand how to write data to Arkiv
Have created your first message/record
Know how to verify your transaction was successful

Content

What We're Doing

You're about to write your first piece of data to Arkiv! This is a blockchain transaction - your message will be stored on-chain and be independently verifiable.

How It Works

When you submit a message:

Your app creates a transaction with your message data
The transaction is signed with your private key
The transaction is submitted to Arkiv (Mendoza testnet)
The transaction is confirmed on-chain
Your message becomes queryable (may take a few seconds due to indexer lag)

Data Flow - Write

This diagram shows the complete write flow: from user action through API route, wallet signing, Arkiv transaction, to final blockchain confirmation. Notice that the transaction is confirmed on-chain immediately, but indexers need time to process it (5-30 seconds delay. This is normal!).

Data Flow - Read

Reading data from Arkiv is simpler than writing. No authentication is needed, and it's free! Queries go to Arkiv indexers, which filter entities by your criteria and return matching results.

Entity Structure

Every piece of data in Arkiv is stored as an entity. Understanding entity structure is key to building effective queries. Use attributes for anything you want to query on (they're indexed and fast), and store complex data in the payload as JSON.

I'm at step 5: Create Your First Record.

Help me:
1. Navigate to the hello-world demo page
2. Submit my first message to Arkiv
3. Understand what happens when I submit (transaction flow)
4. Verify my message appears in the list

Explain the transaction flow and indexer lag.

Update the internal implementation plan with notes and show me the plan so I can track your progress.

✓ Checkpoint

I've navigated to the hello-world demo page
I've submitted at least one message
My message appears in the list (after refreshing)
I can see both the Entity and Transaction links
I understand the difference between entities (data) and transactions (blockchain operations)
I understand that indexer lag is normal

Troubleshooting

Q: I get an error "ARKIV_PRIVATE_KEY environment variable is required". A: Make sure you've completed step 3 (Set Environment Variables) and your .env file has ARKIV_PRIVATE_KEY set. Restart the dev server after updating .env.

Q: My message doesn't appear after submitting. A: This is normal! Due to indexer lag, it can take 5-30 seconds for messages to appear. Click "Refresh" after waiting a moment.

Q: I get a transaction timeout error. A: The testnet can be slow. Your transaction may still be processing. Wait 30 seconds and refresh. If it persists, check that you have testnet tokens in your wallet. If you need more tokens, visit the Mendoza Testnet Faucet.

Q: I get an "insufficient funds" error. A: You need testnet tokens to pay for gas fees. Visit the Mendoza Testnet Faucet to get 0.001 ETH test tokens. Make sure you're using the wallet address that matches your ARKIV_PRIVATE_KEY in your .env file.

Q: How do I know if my transaction succeeded? A: Check the browser console for any errors. If you see a success message or the form clears, the transaction was submitted. Use "View on Explorer" to verify on-chain.

Q: Can I submit multiple messages? A: Yes! Try submitting a few messages to see them all appear in the list.