Shipping & freight jobs

A freight job (collateralized haul) is an on-chain agreement on Sui: SUI sits in escrow, a courier commits with a bond, cargo moves between two SSUs in EVE Frontier, and payouts follow rules everyone can read on-chain.

Who does what

Discovery in Shop or Cargo Well does not move cargo by itself. A goods cross Prefill haul still needs you (or a builder intent) to sign create. The resulting Open haul is the freight book until a courier accepts.

Dual book (goods + freight)

1. Buyer posts a bid with dropoff SSU and a freight bid.
2. When that bid clears an ask, Prefill haul (or a builder create-haul intent the buyer already signed) locks goods + freight on-chain after you sign create.
3. Couriers see the Open job on Shipping. If freight is too low, the shipper uses My orders → Raise freight → Cancel & recreate (one sign refunds both escrows, then a prefilled create form).
4. Optional courier asks rest a minimum freight. When an Open haul pays enough, Pelusium prompts Accept on Shipping — the courier still signs accept_haul_job. Asks are not auto-accepted.

The journey of one haul

Create job  →  Courier accepts  →  Pickup owner approves  →  Execute pickup  →  Execute deliver  →  Payout
   (shipper)      (courier)         (pickup SSU owner)        (courier)          (courier)

1. Create

The shipper defines:

• Pickup SSU and drop-off SSU
• Cargo type and quantity
• Freight payment (courier escrow) and optional goods payment (seller escrow)
• Delivery time window and courier bond requirement

A small protocol fee may apply when funds are released—the app shows amounts before you sign.

2. Accept

A courier accepts the open job and locks a bond on-chain. Until someone accepts, the job stays open and the shipper may be able to cancel.

3. Approve pickup (pickup SSU owner)

Before cargo can leave the pickup SSU, whoever holds the OwnerCap for that SSU must approve this haul. This is an anti-raid gate: a random courier cannot drain your storage just because a job exists.

The seller can approve while the job is still open (before a courier accepts) or after accept—but execute pickup requires both accept and approval.

In Pelusium, the pickup owner sees Approve haul pickup on the job card (they paste their OwnerCap object id if needed). Partner listings and shop asks do not skip this—the seller still approves when it is their SSU.

4. Execute pickup

The courier runs execute pickup with their freighter character id. Pelusium withdraws the agreed type/qty from the pickup SSU into the haul flow.

Requirements:

• Pelusium extension authorized on the pickup SSU — see SSU & Pelusium setup
• Pickup approved (step 3)
• Courier wallet matches the accepted job

5. Execute deliver

The courier runs execute deliver at the drop-off SSU with the same character linkage. Cargo is deposited; escrow settles:

• Courier receives freight payment (if on time)
• Goods seller receives goods payment (if you set one)
• Protocol treasury takes its configured share

The drop-off SSU must also have Pelusium authorized.

6. Consolidate (optional last mile)

If the game shows cargo in a character slot but the SSU UI only lists primary storage, use Pelusium SSU consolidate to move stacks into primary on the same SSU. This is not another freight step—it is a follow-up wallet action after delivery. See After delivery — SSU consolidate.

Buying from Cargo Well or a partner ask

When you click Prefill haul on a crossing (or Buy & deliver on a listing without a dest yet):

1. Pelusium opens Create shipping job with pickup SSU, cargo, quantity, goods price, and seller wallet prefilled.
2. You choose your drop-off SSU and confirm freight terms.
3. You sign create as the shipper (buyer)—that locks escrow.
4. From here the job is identical to any other haul: courier accept → seller approve pickup → pickup → deliver.

The partner API only advertises the ask in the Well. Pickup and delivery still use the same SSU and haul rules as a native storefront sale.

Planning the route

Before creating or accepting a job, use Shipping → Routing to estimate the path between systems. The planner uses ship, fuel, cargo mass, and jump assumptions—it does not lock escrow or change job state. See Route planner.

Cancellations and edge cases

Depending on job state and deployed rules:

• Shipper cancel while the job is still open (no courier yet).
• Mutual cancel while accepted but before pickup (shipper and courier agree).
• After pickup, there is no mutual cancel—outcomes are deliver, late deliver (courier may forfeit freight pay), or overdue refund to the shipper.

The app only offers actions your wallet is allowed to take on that job. See FAQ for common payout questions.

How this relates to Shop

Shop listings, partner Cargo Well asks, and standing bids (with dest SSU + freight) are the goods book. Open haul jobs plus courier asks are the freight book. Settlement is always a haul job. Details: Shop & Cargo Well.