> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retempo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Arc Blockchain Settlement Layer for Retempo Payments

> Retempo uses Arc Testnet to record immutable settlement proof. Explore the RetempoSettlement contract interface and how to verify transactions.

Arc is Retempo's settlement layer. When you submit a payment through the Retempo API, Retempo's backend constructs and submits the Arc transaction on your behalf — you never interact with the chain directly. This page documents the Arc network details, the RetempoSettlement contract interface, and how to independently verify a settlement using the transaction hash returned in the API response.

## Arc Testnet details

Retempo currently operates on Arc Testnet. Use the details below if you want to query the chain directly or configure a local wallet for exploratory purposes.

| Property         | Value                             |
| ---------------- | --------------------------------- |
| **Network name** | Arc Testnet                       |
| **Chain ID**     | `5042002`                         |
| **RPC URL**      | `https://rpc.testnet.arc.network` |

<Info>
  You do not need to add Arc Testnet to a wallet or hold any native tokens to use Retempo. All on-chain interactions are handled by Retempo's authorized operator wallet.
</Info>

## RetempoSettlement contract

The RetempoSettlement contract is a settlement registry deployed on Arc Testnet. Its sole purpose is to record a compact, immutable proof that a payment occurred between a payer and a merchant. It is **not** a billing engine, an escrow contract, or a token vault — it does not hold funds or execute transfers. Every record it stores was written by Retempo's authorized operator wallet after verifying the payment offchain.

### `recordSettlement`

This is the core write function. Retempo's backend calls it once per settlement after all offchain validation passes.

```solidity theme={null}
function recordSettlement(
    string  calldata invoiceId,
    string  calldata serviceId,
    address          payer,
    address          merchant,
    uint256          amount,
    bytes32          referenceHash,
    uint256          timestamp
) external returns (bytes32 settlementId);
```

| Parameter       | Type      | Description                                              |
| --------------- | --------- | -------------------------------------------------------- |
| `invoiceId`     | `string`  | The Retempo invoice identifier                           |
| `serviceId`     | `string`  | The Retempo service identifier                           |
| `payer`         | `address` | Arc wallet address of the paying party                   |
| `merchant`      | `address` | Arc wallet address of the receiving party                |
| `amount`        | `uint256` | Settled amount in USDC micro-units (6 decimal places)    |
| `referenceHash` | `bytes32` | A 32-byte proof identifier you supply at settlement time |
| `timestamp`     | `uint256` | Unix timestamp of the settlement                         |

The function returns a `settlementId` (a `bytes32` value) that uniquely identifies the record. Only an authorized operator wallet can call `recordSettlement` — any other caller will be rejected.

<Warning>
  Do not attempt to call `recordSettlement` directly. The function enforces an operator allowlist and will revert for unauthorized callers. Submit settlements through `POST /api/v1/settlements` instead.
</Warning>

### `SettlementRecorded` event

Every successful `recordSettlement` call emits this event. Retempo's backend checks for this event in the transaction receipt before marking a settlement CONFIRMED.

```solidity theme={null}
event SettlementRecorded(
    bytes32 indexed settlementId,
    string          invoiceId,
    string          serviceId,
    address indexed payer,
    address indexed merchant,
    uint256         amount,
    bytes32         referenceHash,
    uint256         timestamp
);
```

The `settlementId`, `payer`, and `merchant` fields are indexed, which means you can filter Arc event logs for any combination of those values.

### `getSettlement`

Use this view function to read a settlement record directly from the contract, without going through the Retempo API.

```solidity theme={null}
function getSettlement(bytes32 settlementId)
    external
    view
    returns (SettlementRecord memory);
```

It returns a `SettlementRecord` struct:

```solidity theme={null}
struct SettlementRecord {
    string  invoiceId;
    string  serviceId;
    address payer;
    address merchant;
    uint256 amount;
    bytes32 referenceHash;
    uint256 timestamp;
    address recordedBy;
    bool    exists;
}
```

Check the `exists` field first — if it is `false`, no record with that `settlementId` has been written to the contract.

### `computeSettlementId`

This pure function lets you precompute the `settlementId` for a given set of settlement parameters without submitting a transaction.

```solidity theme={null}
function computeSettlementId(
    string  calldata invoiceId,
    string  calldata serviceId,
    address          payer,
    address          merchant,
    uint256          amount,
    bytes32          referenceHash,
    uint256          timestamp
) public pure returns (bytes32);
```

Use this if you want to derive the expected `settlementId` offchain and verify it against the value returned by the Retempo API or the `SettlementRecorded` event.

<Tip>
  The contract deduplicates settlements automatically. If you submit a `recordSettlement` call with parameters that produce an already-recorded `settlementId`, the transaction reverts with a `SettlementAlreadyRecorded` error. Your `referenceHash` is a key input to the ID — generating a unique one per settlement prevents accidental collisions.
</Tip>

## Verifying a settlement

Once you have a `transactionHash` from the Retempo settlement response, you can independently verify the settlement on Arc Testnet in two ways.

**Using the Arc explorer**

1. Copy the `transactionHash` from your settlement response.
2. Paste it into the Arc Testnet explorer search bar.
3. Open the **Logs** or **Events** tab on the transaction page.
4. Confirm a `SettlementRecorded` event is present with the expected `invoiceId`, `amount`, and `referenceHash`.

**Using the contract view function**

1. Take the `settlementId` from the Retempo API response (or compute it with `computeSettlementId`).
2. Call `getSettlement(settlementId)` on the RetempoSettlement contract via the Arc Testnet RPC (`https://rpc.testnet.arc.network`).
3. Verify that `exists` is `true` and the returned fields match your settlement.

## `referenceHash`

The `referenceHash` is a 32-byte (`bytes32`) value that you generate and supply when submitting a settlement. It acts as a unique proof identifier for the onchain record and is one of the inputs used to compute the `settlementId` — which means a unique `referenceHash` guarantees a unique settlement ID.

**Format:** `0x` followed by exactly 64 hexadecimal characters.

**Example:** `0xabc123...def456`

You can generate a valid `referenceHash` in several ways. The example below uses [ethers.js](https://docs.ethers.org/):

```javascript theme={null}
import { keccak256, toUtf8Bytes, hexlify, randomBytes } from 'ethers';

// Option 1: Hash from invoice data (deterministic — same inputs produce same hash)
const referenceHash = keccak256(toUtf8Bytes(`${invoiceId}:${Date.now()}`));

// Option 2: Random bytes32 (non-deterministic — unique every time)
const referenceHash = hexlify(randomBytes(32));
```

<Note>
  Option 1 is useful when you want to be able to reproduce the same `referenceHash` from your own records. Option 2 is simpler and guarantees uniqueness, but you must store the value — you cannot regenerate it later.
</Note>

Use whichever approach fits your system, but always pass the exact same value to the Retempo API that you intend to store in your own records. The `referenceHash` you send is written verbatim to the contract.