> For the complete documentation index, see [llms.txt](https://docs.ama.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ama.one/sdk/3.-core-concepts.md).

# 3. Core Concepts

Understanding the fundamental concepts of the Amadeus Protocol SDK.

### Keypairs

Amadeus Protocol uses **BLS12-381** cryptography for all cryptographic operations. Each account has a public/private keypair.

#### Generating Keypairs

```typescript
import { generateKeypair } from '@amadeus-protocol/sdk'

// Generate a new keypair
const keypair = generateKeypair()

console.log('Public Key:', keypair.publicKey) // Base58 encoded
console.log('Private Key:', keypair.privateKey) // Base58 encoded seed (64 bytes)
```

#### Keypair Structure

* **Public Key**: 48-byte BLS12-381 public key, Base58-encoded
* **Private Key**: 64-byte seed, Base58-encoded (also called "Seed64")

#### Deriving Public Keys

```typescript
import { derivePublicKeyFromSeedBase58 } from '@amadeus-protocol/sdk'

// Derive public key from existing seed
const publicKey = derivePublicKeyFromSeedBase58('5Kd3N...')
console.log('Public Key:', publicKey)
```

### Addresses

In Amadeus Protocol, **public keys serve as addresses**. They are Base58-encoded 48-byte BLS12-381 public keys.

#### Address Format

```typescript
// Address is the public key
const address = keypair.publicKey
// Example: "5Kd3NvsngHeMoo884xkJ6Cyb5StvnRN6f9tYiqwqJzLpQq"
```

#### Address Characteristics

* **Length**: Typically 87-88 characters (Base58 encoded)
* **Format**: Base58-encoded public key
* **Uniqueness**: Each keypair has a unique address
* **Public**: Safe to share publicly (it's your public key)

#### Address Validation

```typescript
import { fromBase58 } from '@amadeus-protocol/sdk'

function isValidAddress(address: string): boolean {
	try {
		const bytes = fromBase58(address)
		return bytes.length === 48 // BLS12-381 public key is 48 bytes
	} catch {
		return false
	}
}
```

### Transactions

Transactions are the primary way to interact with the Amadeus blockchain. They must be:

1. **Built** with proper structure
2. **Signed** with the sender's private key
3. **Serialized** (packed) into binary format
4. **Submitted** to a node

#### Transaction Structure

```typescript
interface UnsignedTransaction {
	signer: Uint8Array // Sender's public key (48 bytes)
	nonce: bigint // Transaction nonce
	action: TransactionAction // Transaction action
}

interface TransactionAction {
	op: 'call' // Operation type
	contract: string // Contract name or address
	function: string // Function to call
	args: SerializableValue[] // Function arguments
}
```

#### Transaction Lifecycle

```typescript
import { TransactionBuilder } from '@amadeus-protocol/sdk'

const builder = new TransactionBuilder(privateKey)

// 1. Build unsigned transaction
const unsignedTx = builder.buildTransfer({
	recipient: address,
	amount: 10.5,
	symbol: 'AMA'
})

// 2. Sign the transaction
const { txHash, txPacked } = builder.sign(unsignedTx)

// 3. Submit to blockchain
const result = await sdk.transaction.submit(txPacked)
```

#### Transaction Nonces

Nonces are automatically generated using timestamps:

```typescript
// Nonce is generated as: BigInt(Date.now()) * 1_000_000n
// This ensures uniqueness for transactions
```

For high-frequency transactions, ensure sufficient time between transactions to avoid nonce collisions.

### Amounts

AMA tokens use **9 decimal places**. Always use atomic units for transactions.

#### Converting Amounts

```typescript
import { toAtomicAma, fromAtomicAma } from '@amadeus-protocol/sdk'

// Convert to atomic units (for transactions)
const atomic = toAtomicAma(1.5) // Returns 1500000000

// Convert from atomic units (for display)
const human = fromAtomicAma(1500000000) // Returns 1.5
```

#### Amount Precision

Always use `toAtomicAma` when building transactions:

```typescript
// ✅ Good
const amount = toAtomicAma(1.5)

// ❌ Bad - may lose precision
const amount = 1.5 * 1000000000
```

### Serialization

The SDK uses **VecPack** canonical serialization for deterministic encoding of transaction data.

#### Encoding

```typescript
import { encode } from '@amadeus-protocol/sdk'

const data = {
	foo: 'bar',
	count: 42,
	items: [1, 2, 3]
}

const encoded = encode(data) // Returns Uint8Array
```

#### Decoding

```typescript
import { decode } from '@amadeus-protocol/sdk'

const decoded = decode(encoded) // Returns DecodedValue
```

#### Supported Types

* `null`
* `boolean`
* `number` / `bigint`
* `string`
* `Uint8Array`
* Arrays
* Objects / Maps

### Signing

Transactions are signed using BLS12-381 signatures over the transaction hash.

#### Signing Process

1. Build transaction structure
2. Serialize transaction (canonical encoding)
3. Hash the serialized transaction (SHA-256)
4. Sign the hash with private key (BLS12-381)
5. Pack transaction with signature

```typescript
// The SDK handles all of this automatically
const { txHash, txPacked } = builder.sign(unsignedTx)
```

### Encoding Formats

#### Base58

Used for addresses, keys, and transaction hashes:

```typescript
import { toBase58, fromBase58 } from '@amadeus-protocol/sdk'

// Encode bytes to Base58
const encoded = toBase58(new Uint8Array([1, 2, 3]))

// Decode Base58 to bytes
const decoded = fromBase58('5Kd3N...')
```

#### Base64

Used for encrypted data and binary payloads:

```typescript
import { uint8ArrayToBase64, base64ToUint8Array } from '@amadeus-protocol/sdk'

// Encode to Base64
const base64 = uint8ArrayToBase64(bytes)

// Decode from Base64
const bytes = base64ToUint8Array(base64)
```

### Encryption

The SDK provides password-based encryption for securing sensitive data.

#### Encrypting Data

```typescript
import { encryptWithPassword } from '@amadeus-protocol/sdk'

// Encrypt private key before storage
const encrypted = await encryptWithPassword(privateKey, userPassword)
// Returns: { encryptedData, iv, salt } (all Base64 encoded)
```

#### Decrypting Data

```typescript
import { decryptWithPassword } from '@amadeus-protocol/sdk'

// Decrypt when needed
const decrypted = await decryptWithPassword(encrypted, userPassword)
```

#### Security Features

* **AES-GCM** encryption with 256-bit keys
* **PBKDF2** key derivation with 100,000 iterations
* Unique salt and IV for each encryption
* Authenticated encryption (prevents tampering)

### API Client

The SDK provides a unified API client for interacting with Amadeus nodes.

#### Initialization

```typescript
import { AmadeusSDK } from '@amadeus-protocol/sdk'

const sdk = new AmadeusSDK({
	baseUrl: 'https://nodes.amadeus.bot/api',
	timeout: 30000
})
```

#### API Modules

* `sdk.chain` - Chain queries (tip, stats, entries)
* `sdk.wallet` - Wallet operations (balances, transactions)
* `sdk.transaction` - Transaction submission
* `sdk.contract` - Contract interactions
* `sdk.epoch` - Epoch and validator data
* `sdk.peer` - Network peer information
* `sdk.proof` - Validator proofs

### Error Handling

All SDK errors are instances of `AmadeusSDKError`:

```typescript
import { AmadeusSDKError } from '@amadeus-protocol/sdk'

try {
	const balance = await sdk.wallet.getBalance(address, 'AMA')
} catch (error) {
	if (error instanceof AmadeusSDKError) {
		console.error('SDK Error:', error.message)
		console.error('Status:', error.status)
		console.error('Response:', error.response)
	}
}
```

### Next Steps

Now that you understand the core concepts:

1. [**Transaction Building**: Learn how to build and sign transactions](/sdk/4.-transaction-building.md)
2. [**API Modules**: Explore all available API endpoints](/sdk/5.-api-modules.md)
3. [**Utilities**: Discover utility functions](/sdk/6.-utilities.md)
4. [**Examples**: See real-world usage examples](/sdk/7.-examples.md)