### Install Olifanton Interop

Source: https://context7.com/olifanton/interop/llms.txt

Use Composer to install the Olifanton Interop library.

```bash
composer require olifanton/interop
```

--------------------------------

### Load String from Slice

Source: https://context7.com/olifanton/interop/llms.txt

Illustrates reading a string from a Slice. This example creates a new cell and slice specifically for reading a string.

```php
// Read string
$slice2 = (new Builder())->writeString("Test")->cell()->beginParse();
$str = $slice2->loadString();         // Reads remaining bytes as string
```

--------------------------------

### Create and Use Hashmap with Custom Serializers in PHP

Source: https://context7.com/olifanton/interop/llms.txt

Demonstrates creating a Hashmap with custom serializers for 32-bit keys and BigInteger values, including setting, getting, checking existence, deleting, adding, replacing, and iterating over entries. Also shows serialization to a Cell and parsing back.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Boc\Hashmap;
use Olifanton\Interop\Boc\HashmapE;
use Olifanton\Interop\Boc\DictSerializers;
use Olifanton\Interop\Boc\Builder;
use Olifanton\Interop\Boc\Cell;
use Brick\Math\BigInteger;

// Create a Hashmap with 32-bit keys and custom serializers
$dict = new Hashmap(
    32, // Key size in bits
    new DictSerializers(
        // Key serializer: convert int to bit array
        keySerializer: static fn(int $key, int $keySize): array =>
            (new Builder())->writeInt($key, $keySize)->cell()->bits->toBitsA(),
        // Key deserializer: convert bit array to int
        keyDeserializer: static fn(array $bits, int $keySize): int =>
            (new Builder())->writeBitArray($bits)->cell()->beginParse()->loadInt($keySize)->toInt(),
        // Value serializer: convert BigInteger to Cell
        valueSerializer: static fn(BigInteger $value): Cell =>
            (new Builder())->writeUint($value, 128)->cell(),
        // Value deserializer: convert Cell to BigInteger
        valueDeserializer: static fn(Cell $cell): BigInteger =>
            $cell->beginParse()->loadUint(128),
    )
);

// Set values
$dict->set(1, BigInteger::fromBase("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF", 16));
$dict->set(2, BigInteger::of(1000));
$dict->set(-5, BigInteger::of(500));

// Get values
$value = $dict->get(1);               // Returns BigInteger
echo $value->toBase(10);              // 340282366920938463463374607431768211455

// Check if key exists
$exists = $dict->has([0, 0, 0, 1]);   // Raw bit array key
$dict->isEmpty();                     // false

// Delete key
$dict->delete(2);

// Add only if not exists
$dict->add(3, BigInteger::of(300));   // Adds only if key 3 doesn't exist

// Replace only if exists
$dict->replace(1, BigInteger::of(999)); // Replaces only if key 1 exists

// Get all keys
$keys = $dict->keys();

// Iterate over dictionary
foreach ($dict as $key => $value) {
    echo "Key: $key, Value: " . $value->toBase(10) . "\n";
}

// Serialize to Cell
$cell = $dict->cell();
$boc = $cell->toBoc();

// Parse Hashmap from Cell
$parsedDict = Hashmap::parse(32, $cell, new DictSerializers(/* ... */));

// Using predefined serializers for common types
$intKeyDict = new Hashmap(
    32,
    DictSerializers::intKey(isBigInt: false)
        ->combine(DictSerializers::uintValue(128))
);
$intKeyDict->set(1, BigInteger::of(100));
$intKeyDict->set(-10, BigInteger::of(200));

$uintKeyDict = new Hashmap(
    256,
    DictSerializers::uintKey(isBigInt: true)
        ->combine(DictSerializers::intValue(64))
);

// HashmapE (Empty-allowed Hashmap)
$emptyDict = new HashmapE(32);        // Can be empty
$emptyCell = $emptyDict->cell();      // Valid even when empty

```

--------------------------------

### Slice get() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Retrieve a specific bit value from a Slice at a given position without advancing the cursor.

```php
/**
 * @param int $n
 */
public function get(int $n): bool
```

--------------------------------

### Get Address Hash Part (Account ID)

Source: https://github.com/olifanton/interop/blob/main/README.md

Obtain the Account ID (hash part) of an Address instance.

```php
public function getHashPart(): Uint8Array
```

--------------------------------

### Get Used Bits in BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the total number of bits that have been written to the BitString.

```php
public function getUsedBits(): int
```

--------------------------------

### Get Remaining Bits in BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the number of unused bits available in the BitString.

```php
public function getFreeBits(): int
```

--------------------------------

### Get BitString as Hex String

Source: https://github.com/olifanton/interop/blob/main/README.md

Converts the BitString's content into its hexadecimal string representation. Useful for displaying or transmitting binary data.

```php
toHex(): string
```

--------------------------------

### Get Used Bytes in BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the number of full bytes that have been used in the BitString.

```php
public function getUsedBytes(): int
```

--------------------------------

### Get BitString Length

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the total number of bits currently stored in the BitString. This indicates the size of the binary data.

```php
getLength(): int
```

--------------------------------

### Get Immutable BitString Array

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns an immutable copy of the internal data as a Uint8Array. This prevents accidental modification of the BitString's underlying data.

```php
getImmutableArray(): Uint8Array
```

--------------------------------

### Initialize Hashmap with Custom Serializers

Source: https://github.com/olifanton/interop/blob/main/README.md

Demonstrates initializing a Hashmap with custom closures for key and value serialization. Use this when you need fine-grained control over how data is converted to and from the internal bit array and Cell formats.

```php
use Olifanton\Interop\Boc\Hashmap;
use Olifanton\Interop\Boc\DictSerializers;
use Olifanton\Interop\Boc\Builder;
use Olifanton\Interop\Boc\Cell;
use Brick\Math\BigInteger;

$dict = new Hashmap(
    32, // Key size,

    // KV marshalling setup
    new DictSerializers(
        // closure converts a number into a bit array, using an intermediate cell (created by Builder) and toBitsA() helper method of BitString class
        keySerializer: static fn(int $userFriendlyKey, int $keySize): array => (new Builder())->writeInt($userFriendlyKey, $keySize)->cell()->bits->toBitsA(),
        // closure converts a bit array into a number, using an intermediate cell (created by Builder)
        keyDeserializer: static fn(array $bitsKey, int $keySize): int => (new Builder())->writeBitArray($bitsKey)->cell()->beginParse()->loadInt($keySize)->toInt(),

        // closure writes BigInteger value into Cell
        valueSerializer: static fn(BigInteger $userFriendlyValue): Cell => (new Builder())->writeUint($userFriendlyValue, 128)->cell(),
        // closure loads BigInteger value from Cell
        valueDeserializer: static fn(Cell $internalValue): BigInteger => $internalValue->beginParse()->loadUint(128),
    )
);

// add value to dictionary
$dict->set(1, BigInteger::fromBase("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF", 16));
// now, internal Hashmap storage contains record with key [00000000000000000000000000000001] and Cell value

var_dump($dict->get(1)->toBase(10)); // 340282366920938463463374607431768211455

```

--------------------------------

### Run Tests

Source: https://github.com/olifanton/interop/blob/main/README.md

Command to execute the project's test suite using Composer.

```bash
composer run test

```

--------------------------------

### Get Bit at Specific Position

Source: https://github.com/olifanton/interop/blob/main/README.md

Retrieves the boolean value of a bit at a given position within the BitString.

```php
/**
 * @param int $n Position
 */
public function get(int $n): bool
```

--------------------------------

### Initialize Hashmap with Predefined Serializers

Source: https://github.com/olifanton/interop/blob/main/README.md

Shows how to initialize a Hashmap using predefined serializers from `DictSerializers` for common types like unsigned integers. This approach is more concise than defining custom serializers.

```php
$dict = new Hashmap(
    32,
    DictSerializers::uintKey(isBigInt: false)->combine(DictSerializers::uintValue(128)),
);
$dict->set(1, BigInteger::fromBase("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF", 16));

var_dump($dict->get(1)->toBase(10)); // 340282366920938463463374607431768211455

```

--------------------------------

### Create and Parse Cell to Slice

Source: https://context7.com/olifanton/interop/llms.txt

Demonstrates creating a cell with various data types using Builder and then parsing it into a Slice to read the data.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Boc\Builder;
use Olifanton\Interop\Boc\Cell;
use Olifanton\Interop\Address;
use Brick\Math\BigInteger;

// Create a cell with data
$cell = (new Builder())
    ->writeUint(0x12345678, 32)
    ->writeInt(-100, 16)
    ->writeCoins(BigInteger::of("1000000000"))
    ->writeAddress(new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL"))
    ->writeString("Hello")
    ->cell();

// Parse cell to get a Slice
$slice = $cell->beginParse();
```

--------------------------------

### Clone Repository

Source: https://github.com/olifanton/interop/blob/main/README.md

Clones the Git repository for the Olifanton Interop project and navigates into the project directory. Replace `<YOUR_GITHUB_NAME>` with your actual GitHub username.

```bash
git clone git@github.com:<YOUR_GITHUB_NAME>/interop.git
cd interop

```

--------------------------------

### Crypto Class: Complete TON Message Signing Workflow

Source: https://context7.com/olifanton/interop/llms.txt

Demonstrates a full workflow for creating and signing a TON message. This involves building a message body using Builder, hashing it, signing the hash with Crypto::sign, and then constructing the final signed message Cell.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Crypto;
use Olifanton\Interop\Bytes;
use Olifanton\TypedArrays\Uint8Array;
use Olifanton\Interop\Boc\Builder;
use Olifanton\Interop\Boc\Cell;

$keyPair = Crypto::newKeyPair();

// Create message body
$body = (new Builder())
    ->writeUint(0, 32)                // seqno
    ->writeUint(time() + 60, 32)      // valid until
    ->writeUint(0, 32)                // op code
    ->cell();

// Get body hash
$bodyHash = $body->hash();

// Sign the hash
$signature = Crypto::sign($bodyHash, $keyPair->secretKey);

// Create signed message
$signedMessage = (new Builder())
    ->writeBytes($signature)          // 512 bits (64 bytes)
    ->writeCell($body)
    ->cell();

$boc = $signedMessage->toBoc();
$bocBase64 = Bytes::bytesToBase64($boc);
```

--------------------------------

### Get Address Workchain ID

Source: https://github.com/olifanton/interop/blob/main/README.md

Retrieve the Workchain ID for a given Address instance. Returns -1 for Masterchain and 0 for the basic workchain.

```php
public function getWorkchain(): int
```

--------------------------------

### Slice loadCoins() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Reads a TON amount in nanotoncoins from the Slice and advances the cursor.

```php
/**
 * Reads TON amount in nanotoncoins.
 */
public function loadCoins(): BigInteger
```

--------------------------------

### Load Data from Slice

Source: https://context7.com/olifanton/interop/llms.txt

Shows how to read different data types from a Slice in the order they were written, including integers, coins, addresses, bits, and variable-length integers.

```php
// Read data in the same order it was written
$uint32 = $slice->loadUint(32);       // Returns BigInteger
echo $uint32->toInt();                // 305419896 (0x12345678)

$int16 = $slice->loadInt(16);         // Returns BigInteger
echo $int16->toInt();                 // -100

$coins = $slice->loadCoins();         // Returns BigInteger (nanotoncoins)
echo $coins->toBase(10);              // 1000000000

$address = $slice->loadAddress();     // Returns Address or null
echo $address?->toString();

// Read bits
$bit = $slice->loadBit();             // Returns bool
$bits = $slice->loadBits(8);          // Returns Uint8Array

// Read variable-length unsigned integer
$varUint = $slice->loadVarUint(16);   // Returns BigInteger
```

--------------------------------

### Get Max Cell Depth

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the maximum depth of child cells within a given Cell. This is a property of the cell's structure.

```php
getMaxDepth(): int
```

--------------------------------

### Peek and Skip Data in Slice

Source: https://context7.com/olifanton/interop/llms.txt

Shows how to peek at data without advancing the cursor and how to skip a specified number of bits.

```php
// Peek at data without moving cursor
$previewUint = $slice->preloadUint(8);
$previewBit = $slice->preloadBit();

// Skip data
$slice->skipBits(16);                 // Skip 16 bits
```

--------------------------------

### Address Constructor

Source: https://github.com/olifanton/interop/blob/main/README.md

Instantiate an Address object using a string representation (friendly or raw format) or another Address instance. An InvalidArgumentException is thrown for invalid input.

```php
/**
 * @param string | \Olifanton\Interop\Address $anyForm
 */
public function __construct(string | Address $anyForm)
```

--------------------------------

### Format Address to String

Source: https://github.com/olifanton/interop/blob/main/README.md

Convert an Address instance to its string representation. Optional parameters allow control over user-friendliness, URL safety, bounceability, and testnet flags.

```php
/**
 * @param bool|null $isUserFriendly User-friendly flag
 * @param bool|null $isUrlSafe URL safe encoded flag
 * @param bool|null $isBounceable Bounceable address flag
 * @param bool|null $isTestOnly Testnet Only flag
 */
public function toString(?bool $isUserFriendly = null,
                         ?bool $isUrlSafe = null,
                         ?bool $isBounceable = null,
                         ?bool $isTestOnly = null): string
```

--------------------------------

### Get BitString from Cell

Source: https://github.com/olifanton/interop/blob/main/README.md

Retrieves the internal BitString instance associated with a Cell. This allows for reading and writing bits within the cell's data.

```php
getBits(): BitString
```

--------------------------------

### Get References (Child Cells) from Cell

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns an Array-like object containing all child Cells (references) of the current Cell. This is useful for traversing the cell structure.

```php
getRefs(): ArrayObject<Cell>
```

--------------------------------

### Slice loadUint() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Read an unsigned integer from the Slice and advance the cursor. Specify the bit length of the integer.

```php
/**
 * @param int $bitLength
 */
public function loadUint(int $bitLength): BigInteger
```

--------------------------------

### Slice loadAddress() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Reads an Address from the Slice and advances the cursor.

```php
/**
 * Reads Address.
 */
public function loadAddress(): ?Address
```

--------------------------------

### Create and Serialize a TON Cell

Source: https://context7.com/olifanton/interop/llms.txt

Demonstrates creating a new Cell, writing various data types (Uint, Address, String), adding child cells, and serializing to BoC format. Includes options for BoC serialization and deserialization.

```php
<?php declare(strict_types=1);

use Olifanton
ások\Boc\Cell;
use Olifanton
ások\Boc\Builder;
use Olifanton
ások\Address;
use Olifanton
ások\Bytes;

// Create a new empty cell
$cell = new Cell();

// Write data to cell's BitString
$cell->bits->writeUint(123, 32);
$cell->bits->writeAddress(new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL"));

// Add child cell references (max 4 refs)
$childCell = new Cell();
$childCell->bits->writeString("Child data");
$cell->refs[] = $childCell;

// Write another cell's content
$anotherCell = new Cell();
$anotherCell->bits->writeUint(456, 16);
$cell->writeCell($anotherCell);

// Serialize cell to Bag of Cells (BoC) format
$bocBytes = $cell->toBoc();           // Returns Uint8Array
$bocHex = Bytes::bytesToHexString($bocBytes);
$bocBase64 = Bytes::bytesToBase64($bocBytes);

// Serialize with options
$bocBytes = $cell->toBoc(
    has_idx: true,
    hash_crc32: true,
    has_cache_bits: false,
    flags: 0
);

// Deserialize BoC to cells
$cells = Cell::fromBoc($bocHex);      // Returns array of root cells
$singleCell = Cell::oneFromBoc($bocHex); // Get single root cell

// Parse base64-encoded BoC
$cell = Cell::oneFromBoc($bocBase64, isBase64: true);

// Get cell hash (SHA-256)
$hash = $cell->hash();                // Returns Uint8Array (32 bytes)
$hashHex = Bytes::bytesToHexString($hash);

// Get cell depth
$depth = $cell->getMaxDepth();

// Print cell structure (Fift-style)
echo $cell->print();
// Output: x{...}
//          x{...}

// Access cell properties
$bits = $cell->getBits();             // Get BitString
$refs = $cell->getRefs();             // Get ArrayObject of child cells

// Parse cell to read data (returns Slice)
$slice = $cell->beginParse();

```

--------------------------------

### Builder Class

Source: https://github.com/olifanton/interop/blob/main/README.md

Provides methods for creating cells efficiently.

```APIDOC
## Builder Class

### Description
The `Builder` class facilitates the creation of cells within a `BitString` instance. All `Builder` instances are mutable, and methods return the same instance. The interface largely mirrors that of the `BitString` class.
```

--------------------------------

### Check Remaining Data in Slice

Source: https://context7.com/olifanton/interop/llms.txt

Demonstrates how to check the amount of remaining unread bits and the total bits that are left to read in a Slice.

```php
// Check remaining data
echo $slice->getFreeBits();           // Remaining unread bits
echo $slice->getUsedBits();           // Bits left to read
```

--------------------------------

### Handle Specific Data Structures

Source: https://github.com/olifanton/interop/blob/main/tests/stub-data/boc/block1.base64.txt

Demonstrates handling of specific data structures, including nested lists and dictionaries. This is crucial for complex data interoperability.

```python
def handle_complex_data(data):
    output = []
    for item in data:
        if isinstance(item, dict):
            # Process dictionary items
            processed_dict = {k: v.upper() if isinstance(v, str) else v for k, v in item.items()}
            output.append(processed_dict)
        elif isinstance(item, list):
            # Process list items
            processed_list = [str(sub_item) + '_processed' for sub_item in item]
            output.append(processed_list)
        else:
            output.append(str(item) + '_other')
    return output

# Example usage:
complex_data = [{"name": "Alice", "age": 30}, [1, 2, 3], "simple_string"]
processed_complex_data = handle_complex_data(complex_data)
print(f"Processed complex data: {processed_complex_data}")
```

--------------------------------

### Slice loadBits() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Read an array of bits from the Slice and advance the cursor by the specified bit length.

```php
/**
 * @param int $bitLength
 */
public function loadBits(int $bitLength): Uint8Array
```

--------------------------------

### Slice loadVarUint() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Read a variable-length unsigned integer from the Slice and advance the cursor. Specify the maximum bit length.

```php
/**
 * @param int $bitLength
 */
public function loadVarUint(int $bitLength): BigInteger
```

--------------------------------

### Create TON Cells with Fluent Builder Interface

Source: https://context7.com/olifanton/interop/llms.txt

Utilizes the Builder class for a fluent interface to construct TON Cells. Shows writing various data types, optional values, and cell references. The `cell()` method finalizes the construction.

```php
<?php declare(strict_types=1);

use Olifanton
ások\Boc\Builder;
use Olifanton
ások\Boc\Cell;
use Olifanton
ások\Address;
use Brick\Math\BigInteger;

// Create a cell using Builder (fluent interface)
$cell = (new Builder())
    ->writeUint(0x12345678, 32)
    ->writeInt(-100, 16)
    ->writeCoins(BigInteger::of("1000000000")) // 1 TON
    ->writeAddress(new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL"))
    ->writeString("Hello")
    ->cell();

// Write bits
$cell = (new Builder())
    ->writeBit(1)
    ->writeBit(true)
    ->writeBitArray([1, 0, 1, 1])
    ->cell();

// Write optional values (Maybe types in TL-B)
$cell = (new Builder())
    ->writeMaybeUint(100, 32)     // Writes 1 bit (true) + value
    ->writeMaybeUint(null, 32)    // Writes 1 bit (false)
    ->writeMaybeInt(-50, 16)      // Writes 1 bit (true) + value
    ->writeMaybeInt(null, 16)     // Writes 1 bit (false)
    ->writeMaybeCoins(BigInteger::of("500000000"))
    ->writeMaybeCoins(null)
    ->cell();

// Add cell references
$refCell1 = (new Builder())->writeUint(1, 8)->cell();
$refCell2 = (new Builder())->writeUint(2, 8)->cell();

$cell = (new Builder())
    ->writeUint(0, 32)
    ->writeRef($refCell1)         // Add child reference
    ->writeRef($refCell2)
    ->writeMaybeRef(null)         // Optional reference
    ->cell();

// Write another cell's content
$partialCell = (new Builder())->writeUint(100, 8)->cell();
$fullCell = (new Builder())
    ->writeUint(1, 8)
    ->writeCell($partialCell)     // Copies bits and refs
    ->writeUint(2, 8)
    ->cell();

// Get the constructed cell
$finalCell = (new Builder())
    ->writeUint(42, 32)
    ->cell();

// Serialize to BoC
$boc = $finalCell->toBoc();

```

--------------------------------

### Check if Address is User-Friendly

Source: https://github.com/olifanton/interop/blob/main/README.md

Check if the Address instance is represented in a user-friendly format.

```php
public function isUserFriendly(): bool
```

--------------------------------

### Slice Constructor

Source: https://github.com/olifanton/interop/blob/main/README.md

Initialize a Slice object with a Uint8Array, its length, and an array of cell slices (references).

```php
/**
 * @param \Olifanton\TypedArrays\Uint8Array $array
 * @param int $length
 * @param \Olifanton\Interop\Boc\Slice[] $refs
 */
public function __construct(Uint8Array $array, int $length, array $refs)
```

--------------------------------

### Initialize BitString with Length

Source: https://github.com/olifanton/interop/blob/main/README.md

Create a BitString instance with a specified length. The default length for TVM Cells is 1023 bits. Writing beyond the allocated length will throw a BitStringException.

```php
/**
 * @param int $length
 */
public function __construct(int $length)
```

--------------------------------

### Convert TON to Nanotoncoins and Vice Versa in PHP

Source: https://context7.com/olifanton/interop/llms.txt

Provides helper methods for converting between TON (human-readable) and nanotoncoins (blockchain format), including custom decimal support for other currencies like USDt.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Units;
use Brick\Math\BigInteger;

// Convert TON to nanotoncoins
$nano = Units::toNano(1);             // 1000000000 (1 TON)
$nano = Units::toNano(0.5);           // 500000000 (0.5 TON)
$nano = Units::toNano("1.5");         // 1500000000 (1.5 TON)
$nano = Units::toNano(0.001);         // 1000000 (0.001 TON)

// Convert nanotoncoins to TON
$ton = Units::fromNano(1000000000);   // 1
$ton = Units::fromNano(500000000);    // 0.5
$ton = Units::fromNano("1500000000"); // 1.5
$ton = Units::fromNano(BigInteger::of("2000000000")); // 2

// Custom decimals (e.g., for USDt which uses 6 decimals)
$usdtNano = Units::toNano(100, Units::USDt);    // 100000000
$usdtAmount = Units::fromNano(100000000, Units::USDt); // 100

// Default decimals constant
echo Units::DEFAULT; // 9 (TON decimals)
echo Units::USDt;    // 6 (USDT decimals)

// Use with Builder for writing coins
use Olifanton\Interop\Boc\Builder;

$cell = (new Builder())
    ->writeCoins(Units::toNano(1.5))  // Write 1.5 TON
    ->cell();

// Read coins and convert
$slice = $cell->beginParse();
$nanoCoins = $slice->loadCoins();
$tonAmount = Units::fromNano($nanoCoins);
echo $tonAmount; // 1.5

```

--------------------------------

### Handle Cell References in Slice

Source: https://context7.com/olifanton/interop/llms.txt

Explains how to load, parse, and read data from nested cells referenced within a parent cell's Slice. It also covers optional references and skipping references.

```php
// Work with cell references
$parentCell = (new Builder())
    ->writeUint(1, 8)
    ->writeRef((new Builder())->writeUint(100, 32)->cell())
    ->writeRef((new Builder())->writeUint(200, 32)->cell())
    ->cell();

$parentSlice = $parentCell->beginParse();
$parentSlice->loadUint(8);            // Read parent data first

$childCell1 = $parentSlice->loadRef();// Returns Cell
$childSlice1 = $childCell1->beginParse();
echo $childSlice1->loadUint(32)->toInt(); // 100

$childCell2 = $parentSlice->loadRef();
echo $childCell2->beginParse()->loadUint(32)->toInt(); // 200

// Optional reference
$maybeRef = $parentSlice->loadMaybeRef(); // Returns Cell or null

// Skip reference
$parentSlice->skipRef();

// Get refs count
echo $parentSlice->getRefsCount();
echo $parentSlice->getRemainingRefsCount();
```

--------------------------------

### Clone BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Creates and returns a deep copy (clone) of the current BitString instance. The new instance is independent of the original.

```php
clone(): BitString
```

--------------------------------

### Include Autoloader in PHP Project

Source: https://github.com/olifanton/interop/blob/main/README.md

Include the Composer autoloader script to make Olifanton Interop classes available in your PHP project. Ensure you have declared strict types.

```php
<?php declare(strict_types=1);

require __DIR__ . "/vendor/autoload.php";

use Olifanton\Interop\Boc\BitString;
use Olifanton\Interop\Boc\Cell;

// Now you can use Interop classes

```

--------------------------------

### Process Large Data Files

Source: https://github.com/olifanton/interop/blob/main/tests/stub-data/boc/block1.base64.txt

Demonstrates efficient processing of large data files by reading them in chunks. This prevents memory exhaustion for big datasets.

```python
def process_large_file(filepath, chunk_size=1024):
    """Processes a large file by reading it in chunks."""
    processed_lines = 0
    with open(filepath, 'r') as f:
        while True:
            chunk = f.read(chunk_size)
            if not chunk:
                break
            # Process the chunk (e.g., count lines, extract info)
            processed_lines += chunk.count('\n')
            # Simulate processing
            pass
    return processed_lines

# Example usage (assuming 'large_data.txt' exists):
# try:
#     total_lines = process_large_file('large_data.txt')
#     print(f"Total lines processed: {total_lines}")
# except FileNotFoundError:
#     print("Error: large_data.txt not found.")
```

--------------------------------

### Slice loadInt() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Read a signed integer from the Slice and advance the cursor. Specify the bit length of the integer.

```php
/**
 * @param int $bitLength
 */
public function loadInt(int $bitLength): BigInteger
```

--------------------------------

### Create Feature Branch

Source: https://github.com/olifanton/interop/blob/main/README.md

Creates and checks out a new Git branch for developing a feature or hotfix. Replace `<FEATURE_NAME>` with a descriptive name for your changes.

```bash
git branch feature/<FEATURE_NAME>
git checkout feature/<FEATURE_NAME>

```

--------------------------------

### Slice loadBit() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Reads a single bit from the Slice and advances the cursor.

```php
/**
 * Reads a bit and moves the cursor.
 */
public function loadBit(): bool
```

--------------------------------

### Iterate BitString Bits

Source: https://github.com/olifanton/interop/blob/main/README.md

Iterates through the bits of a BitString. Ensure the BitString is initialized and bits are written before iterating.

```php
<?php declare(strict_types=1);

use Olifanton
Interop\Boc\BitString;

$bs = new BitString(4);
$bs->writeBit(1);
$bs->writeBit(0);
$bs->writeBit(1);
$bs->writeBit(1);

foreach ($bs->iterate() as $b) {
    echo (int)$b;
}
// Prints "1011"
```

--------------------------------

### Create BoC Byte Array with toBoc()

Source: https://github.com/olifanton/interop/blob/main/README.md

Use toBoc() to create a BoC Byte array from a cell. Optional parameters control indexing, CRC32 hashing, and cache bits.

```php
/**
 * @param bool $has_idx Default _true_
 * @param bool $hash_crc32 Default _true_
 * @param bool $has_cache_bits Default _false_
 * @param int $flags Default _0_
 */
public function toBoc(bool $has_idx = true,
                      bool $hash_crc32 = true,
                      bool $has_cache_bits = false,
                      int  $flags = 0): Uint8Array
```

--------------------------------

### Work with TON Addresses in PHP

Source: https://context7.com/olifanton/interop/llms.txt

The Address class handles TON smart contract addresses in various formats (user-friendly, raw) and provides methods for validation, property retrieval, conversion, and comparison.

```php
<?php declare(strict_types=1);

require __DIR__ . "/vendor/autoload.php";

use Olifanton\Interop\Address;

// Create address from user-friendly format
$address = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");

// Create address from raw format
$rawAddress = new Address("-1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260");

// Validate an address
$isValid = Address::isValid("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL"); // true
$isValid = Address::isValid("invalid-address"); // false

// Get address properties
echo $address->getWorkchain();    // 0 (basic workchain) or -1 (masterchain)
echo $address->isBounceable();    // true/false
echo $address->isTestOnly();      // true/false
echo $address->isUserFriendly();  // true/false

// Convert address to different formats
echo $address->toString(); // Original format
echo $address->toString(
    isUserFriendly: true,
    isUrlSafe: true,
    isBounceable: false,
    isTestOnly: false
); // Custom format

// Helper methods for common formats
echo $address->asWallet();   // Non-bounceable, URL-safe (for wallets)
echo $address->asContract(); // Bounceable, URL-safe (for contracts)

// Compare addresses
$addr1 = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");
$addr2 = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");
$areEqual = $addr1->isEqual($addr2); // true

// Get zero address
$zeroAddr = Address::zero();
```

--------------------------------

### toBoc() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Creates a BoC (Bag of Cells) byte array from the current state.

```APIDOC
## toBoc()

### Description
Creates a BoC byte array.

### Method
`toBoc(has_idx: bool = true, hash_crc32: bool = true, has_cache_bits: bool = false, flags: int = 0): Uint8Array`

### Parameters
#### Query Parameters
- **has_idx** (bool) - Optional - Default: `true`
- **hash_crc32** (bool) - Optional - Default: `true`
- **has_cache_bits** (bool) - Optional - Default: `false`
- **flags** (int) - Optional - Default: `0`

### Response
#### Success Response (200)
- **Uint8Array**: The BoC byte array representation.
```

--------------------------------

### Slice getFreeBits() Method

Source: https://github.com/olifanton/interop/blob/main/README.md

Returns the number of unread bits remaining in the Slice, according to the internal cursor position.

```php
/**
 * Returns the unread bits according to the internal cursor.
 */
public function getFreeBits(): int
```

--------------------------------

### Create Single Cell from Serialized Boc

Source: https://github.com/olifanton/interop/blob/main/README.md

Fetches a single root Cell from a serialized Boc. This is useful when you expect only one root cell. It can handle base64 encoded input.

```php
/**
 * @param string|Uint8Array $serializedBoc Serialized BoC
 * @param bool $isBase64 Base64-serialized flag, default false
 */
public static function oneFromBoc(string|Uint8Array $serializedBoc, bool $isBase64 = false): Cell
```

--------------------------------

### Bytes Class: Hex and String Conversions

Source: https://context7.com/olifanton/interop/llms.txt

Use Bytes::hexStringToBytes to convert hex strings to Uint8Array and Bytes::bytesToHexString for the reverse. Convert PHP strings to Uint8Array with Bytes::stringToBytes and Uint8Array to PHP strings with Bytes::arrayToBytes.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Bytes;
use Olifanton\TypedArrays\Uint8Array;

// Convert hex string to Uint8Array
$bytes = Bytes::hexStringToBytes("48656c6c6f");
// $bytes contains [72, 101, 108, 108, 111] ("Hello" in ASCII)

// Convert Uint8Array to hex string
$hex = Bytes::bytesToHexString($bytes);
echo $hex; // "48656c6c6f"

// Convert PHP string to Uint8Array
$bytes = Bytes::stringToBytes("Hello");
echo $bytes[0]; // 72 (ASCII 'H')

// Convert Uint8Array to PHP string
$str = Bytes::arrayToBytes($bytes);
echo $str; // "Hello"
```

--------------------------------

### Check if Address is Testnet Only

Source: https://github.com/olifanton/interop/blob/main/README.md

Determine if an Address instance is flagged for testnet usage only.

```php
public function isTestOnly(): bool
```

--------------------------------

### Write Unsigned Integer to BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Writes an unsigned integer to the BitString with a specified bit length. Supports standard integers and Brick
Math
BigInteger for arbitrary precision.

```php
/**
 * @param int|
Brick
Math
BigInteger $number Unsigned integer
 * @param int $bitLength Integer size (8, 16, 32, ...)
 */
public function writeUint(int | BigInteger $number, int $bitLength): void
```

--------------------------------

### Write Bit Array to BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Writes an array of bits to a BitString. The array can contain integers (0 or 1) or booleans. Ensure the BitString is initialized before writing.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Boc\BitString;

$bs = new BitString(4);
$bs->writeBitArray([1, false, 0, true]);

foreach ($bs->iterate() as $b) {
    echo (int)$b;
}
// Prints "1001"
```

--------------------------------

### Check if Address is Bounceable

Source: https://github.com/olifanton/interop/blob/main/README.md

Verify if an Address instance has the 'isBounceable' flag set.

```php
public function isBounceable(): bool
```

--------------------------------

### Address Class

Source: https://context7.com/olifanton/interop/llms.txt

The Address class facilitates working with TON smart contract addresses in various formats, including user-friendly (base64) and raw forms, with support for different flags like bounceable and testnet-only.

```APIDOC
## Address Class

### Description
Allows working with TON smart contract addresses in various formats including user-friendly (base64), raw form, and with different flags (bounceable, testnet-only, URL-safe).

### Methods
- `__construct(string $address, bool $isUserFriendly = true)`: Creates an Address object.
- `isValid(string $address): bool`: Validates a TON address.
- `getWorkchain(): int`: Returns the workchain ID.
- `isBounceable(): bool`: Checks if the address is bounceable.
- `isTestOnly(): bool`: Checks if the address is testnet-only.
- `isUserFriendly(): bool`: Checks if the address is in user-friendly format.
- `toString(bool $isUserFriendly = true, bool $isUrlSafe = true, bool $isBounceable = true, bool $isTestOnly = true): string`: Converts the address to a string in a specified format.
- `asWallet(): string`: Returns the address in a non-bounceable, URL-safe format suitable for wallets.
- `asContract(): string`: Returns the address in a bounceable, URL-safe format suitable for contracts.
- `isEqual(Address $address): bool`: Compares this address with another Address object.
- `zero(): Address`: Returns the zero address.

### Example Usage
```php
<?php declare(strict_types=1);

require __DIR__ . "/vendor/autoload.php";

use Olifanton\Interop\Address;

// Create address from user-friendly format
$address = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");

// Create address from raw format
$rawAddress = new Address("-1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260");

// Validate an address
$isValid = Address::isValid("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL"); // true
$isValid = Address::isValid("invalid-address"); // false

// Get address properties
echo $address->getWorkchain();    // 0 (basic workchain) or -1 (masterchain)
echo $address->isBounceable();    // true/false
echo $address->isTestOnly();      // true/false
echo $address->isUserFriendly();  // true/false

// Convert address to different formats
echo $address->toString(); // Original format
echo $address->toString(
    isUserFriendly: true,
    isUrlSafe: true,
    isBounceable: false,
    isTestOnly: false
); // Custom format

// Helper methods for common formats
echo $address->asWallet();   // Non-bounceable, URL-safe (for wallets)
echo $address->asContract(); // Bounceable, URL-safe (for contracts)

// Compare addresses
$addr1 = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");
$addr2 = new Address("EQBvI0aFLnw2QbZgjMPCLRdtRHxhUyinQudg6sdiohIwg5jL");
$areEqual = $addr1->isEqual($addr2); // true

// Get zero address
$zeroAddr = Address::zero();
```
```

--------------------------------

### Crypto Class: SHA-256 Hashing

Source: https://context7.com/olifanton/interop/llms.txt

Generate a SHA-256 hash of binary data using Crypto::sha256. The input must be a Uint8Array, and the output is a 32-byte Uint8Array representing the hash, which can be converted to a hex string.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Crypto;
use Olifanton\Interop\Bytes;
use Olifanton\TypedArrays\Uint8Array;

// Generate SHA-256 hash
$data = Bytes::stringToBytes("Hello, TON!");
$hash = Crypto::sha256($data);
echo Bytes::bytesToHexString($hash);
// 32-byte hash as hex string
```

--------------------------------

### Write Another BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Appends the content of another BitString instance to the current BitString. This operation merges the bits from the source BitString.

```php
/**
 * @param 
Olifanton
Interop
Boc
BitString $anotherBitString BitString instance
 */
public function writeBitString(BitString $anotherBitString): void
```

--------------------------------

### Crypto Class: Key Pair Generation

Source: https://context7.com/olifanton/interop/llms.txt

Generate a new random Ed25519 key pair using Crypto::newKeyPair, returning an object with publicKey and secretKey properties. Deterministic key pairs can be generated from a seed using Crypto::keyPairFromSeed.

```php
<?php declare(strict_types=1);

use Olifanton\Interop\Crypto;
use Olifanton\Interop\Bytes;
use Olifanton\TypedArrays\Uint8Array;

// Generate a new random key pair
$keyPair = Crypto::newKeyPair();
echo Bytes::bytesToHexString($keyPair->publicKey);  // 32 bytes
echo Bytes::bytesToHexString($keyPair->secretKey);  // 64 bytes

// Generate key pair from seed (deterministic)
$seed = Crypto::newSeed();            // Generate random 32-byte seed
$keyPair = Crypto::keyPairFromSeed($seed);

// Reproducible key generation
$fixedSeed = Bytes::hexStringToBytes(
    "0000000000000000000000000000000000000000000000000000000000000001"
);
$keyPair = Crypto::keyPairFromSeed($fixedSeed);
// Same seed always produces same key pair
```

--------------------------------

### Write Signed Integer to BitString

Source: https://github.com/olifanton/interop/blob/main/README.md

Writes a signed integer to the BitString with a specified bit length. Supports standard integers and Brick
Math
BigInteger for arbitrary precision.

```php
/**
 * @param int|
Brick
Math
BigInteger $number Signed integer
 * @param int $bitLength Integer size (8, 16, 32, ...)
 */
public function writeInt(int | BigInteger $number, int $bitLength): void
```