Logistics hub setup (Pelusium on Sui)

Pelusium connects in-game freight (storage units, characters, cargo) to on-chain jobs on Sui. This guide walks through SSU authorization, creating jobs, and the courier lifecycle.

Prerequisites

• A Sui wallet connected to the app (same network as NEXT_PUBLIC_SUI_NETWORK, e.g. testnet).
• NEXT_PUBLIC_PELUSIUM_PACKAGE_ID set to your published pelusium package, and NEXT_PUBLIC_PELUSIUM_CONFIG_ID set to the shared PelusiumConfig object id (see move/pelusium/README.md and move/pelusium/FIRST_TIME_PUBLISH.md).
• For each storage unit (SSU) you use as pickup or dropoff: the SSU object id and its OwnerCap<StorageUnit> object id (from Suiscan or your explorer — objects owned by your character/wallet).

Authorize Pelusium on each SSU (once per unit)

Before execute_pickup or execute_deliver can use Pelusium on an SSU, that unit’s owner must register the Pelusium extension:

• Pickup SSU owner and dropoff SSU owner each run authorize_pelusium_extension once per SSU (if you own both SSUs, that is two authorizations — one per unit).
• Use the Pelusium SSU setup page in the app, or sign the same transaction from the CLI / another wallet UI.

Creating a freight job does not require authorization to have happened first, but pickup and deliver will fail until the relevant SSUs are authorized.

Security: You cannot authorize someone else’s SSU without their matching OwnerCap; the chain checks OwnerCap against that StorageUnit.

Create a shipping job (shipper)

On Create shipping job, the shipper submits create_freight_job with pickup/dropoff SSU ids, cargo type_id and quantity, SUI escrow (courier payment locked on the job), and optional private job (designated courier wallet). Only that wallet may accept_freight_job while the job is open.

Courier lifecycle (Shipping hub)

1. Accept — Courier calls accept_freight_job with their character id (and wallet must match designated courier if set).
2. Pickup — execute_pickup withdraws the agreed stack from the pickup SSU (type + quantity from the job). Requires Pelusium authorized on the pickup SSU.
3. Deliver — execute_deliver deposits into the recipient character’s owned inventory at the dropoff SSU, then settles escrow: courier receives (total − fee) to the freighter character’s wallet; the protocol treasury receives fee per PelusiumConfig.fee_bps (basis points). Requires Pelusium on the dropoff SSU and the shared PelusiumConfig object in the same transaction. You need the transit Item object id from the pickup transaction effects, and the recipient character id (often the buyer).

Module reference: move/pelusium/README.md in the repository.

Settlement: SUI today, $EVE later

North star: Freight should tie in-game work to real economic value on-chain. SUI is the practical settlement asset now (native on Sui, liquid, used for gas).

The EVE Frontier whitepaper (Abstract) states that EVE Frontier will deploy the $EVE token on Sui. Exact timing is not fixed there. When $EVE exists, both SUI and $EVE live on the same chain — participants can swap between them (DEX / aggregator liquidity permitting). Settling contracts in SUI today is not a dead end for a future $EVE economy.

Current app / Move status

The published freight_contract in this repository locks SUI escrow on create_freight_job (Balance<SUI> on the shared FreightJob). Cancel while Open refunds the full escrow to the shipper. Deliver moves cargo, then pays the courier (minus protocol fee) and sends the fee to the PelusiumConfig treasury address. Configure the treasury and fee_bps via the shared PelusiumConfig object (default fee_bps at publish is 100 = 1%; ProtocolAdminCap can update treasury and fee).

Still out of scope: goods payment between buyer and seller (separate from courier escrow); generic Coin<T> / $EVE settlement (future); refund after Accepted if the courier stops (escrow is only released on deliver or refunded on cancel while Open — see product risk in goals.md Phase B notes).

Buyer/seller payment vs courier freight payment

These are different concerns:

• Freight / logistics: paying the courier for moving cargo (shipper → courier, optionally a Pelusium protocol fee). That is what on-chain escrow for SUI in Pelusium would cover once implemented — tied to create / accept / execute_deliver / cancel.
• Buyer and seller settling the goods themselves (ore price, hull sale, etc.) is usually a separate deal: in-game exchange, another smart contract, OTC transfer, or guild accounting. Pelusium does not automatically move payment from buyer to seller today; you can combine flows in a product later (e.g. one PTB or linked jobs), but that is not the current freight_contract scope.

Troubleshooting

• Dry run failed on authorize or freight txs: wrong object ids, SSU offline, Pelusium not published on this network, or game/world preconditions not met — read the error and confirm SSU + character + job state on the explorer.
• Extension not authorized: Run authorize on that SSU before pickup/deliver on that unit.
• Designated courier: Only that address can accept while the job is Open.