Offline payments for any EVM wallet

What is available today

Portage is built in phases. The SDK's code exists and is held to shared test vectors in three languages, but packaging it for outside developers is Phase 5 work. This table is the honest state of each piece.

Core concepts

Pay and settle are separate

A Portage payment is a signed message, 141 to about 350 bytes, that one phone hands to another by QR code or Bluetooth. It is a claim on the payer's money until it settles on-chain. Settlement happens later, when either phone, or any phone carrying the message, reaches a network. Until the chain reports it at the finalized block, the payment is pending, never "received".

Two balances

• Main balance: USDC at the user's ordinary address. Spendable online, or offline without protection for the receiver.
• Offline balance: USDC the user locked in a personal OfflineVault. It leaves only against a voucher signed by the phone's hardware-bound key, or to the owner after a withdrawal delay of 3 to 30 days.

Assurance tiers

Offline double-spending cannot be prevented by software; Portage bounds it. Every payment arrives with a tier, and the receiver sets limits per tier.

The rule that makes offline safe

A receiver accepts a voucher only if it expires before the earliest moment the vault could be emptied: validBefore ≤ Ts + D − m, where Ts is the snapshot time, D the vault's withdrawal delay and m a safety margin. "Pay offline, then drain the vault online" therefore cannot work. The SDK applies this check for you in ReceiveFlow.accept.

Two keys per user

• Owner key (secp256k1): derived from the 12-word recovery phrase; signs direct payments, deposits and vault operations.
• Voucher key (P-256): generated inside the phone's secure hardware (StrongBox or TEE), never exportable; signs vouchers. The vault verifies it on-chain through Avalanche's P-256 precompile.

Architecture

The SDK is a set of Kotlin modules. The flows hold all payment logic and talk to the outside world only through small interfaces, called ports. Your app supplies the UI and picks implementations for the ports, most of which ship as modules.

• Pure JVM core. ptg-sdk and ptg-protocol have no Android or UI dependency, so every flow unit-tests on a laptop with fakes.
• One wire format, three languages. Kotlin, TypeScript and Solidity all read the same vectors in tools/vectors/*.json, so a payment made by one wallet verifies everywhere.
• Services are optional. With no relayer or attestor, the wallet still pays and settles from the owner's own address over any RPC ("rescue mode").

Installation Coming Soon

A packaged portage-android library on Maven Central, with a reviewed and semantically versioned public API, is planned for Phase 5. When it ships, adding it will look like this:

dependencies {
    // Coming Soon: coordinates and version are not published yet.
    implementation("org.portage:portage-android:1.0.0")
}

Requirements

Quick start

This is how the Portage app wires the SDK today. The samples use the real class names; treat them as an API preview that may change before 1.0.

1. Shared setup

val registry = Registry.DEFAULT                     // networks, tokens, contracts, attestor keys
val network = registry.get(Net.AVALANCHE_FUJI)!!   // Fuji today
val clock = DeviceClock { System.currentTimeMillis() / 1000 }
val rng = SecureRandom()
val random = RandomSource { n -> ByteArray(n).also(rng::nextBytes) }

// ptg-db: one encrypted database implements every store the flows need
val db = PortageDatabase.open(context)
val time = TimeGuard(clock, db)                     // refuses to sign or accept if the clock was set back

// ptg-keystore: keys never leave the keystore; every signature asks for the user
val owner = OwnerKeystore(context, authenticator, promptFor = ::authPrompt)

2. Receive a payment

val receive = ReceiveFlow(registry, network, self = owner.address, store = db, time = time, random = random)

// Show a request as a QR code. amount 0 lets the payer choose.
val (request, qrText) = receive.newRequest(amount = BigInteger.valueOf(2_500_000)) // 2.50 USDC

// Later, with the payer's signed payment (scanned text or Bluetooth bytes):
when (val r = receive.accept(scanned, request)) {
    is ReceiveFlow.Outcome.Accepted -> showPending(r.record)          // verified, then stored: PENDING
    is ReceiveFlow.Outcome.AlreadyReceived -> showPending(r.record)   // scanned twice: not an error
    is ReceiveFlow.Outcome.Rejected -> explain(r.code)                // E_SIG, E_EXPIRY, E_POLICY, …
    ReceiveFlow.Outcome.ClockBlocked -> askToFixClock()
}

3. Pay

val pay = PayFlow(registry, network, signer = owner, store = db, time = time, random = random)

val request = (pay.parse(scannedRequest) as? PayFlow.Parsed.Ok)?.request ?: return
when (val q = pay.quote(request)) {
    is PayFlow.QuoteResult.Ok -> {
        // q.quote.options lists every tier with its fee, or why it is blocked
        when (val s = pay.sign(q.quote)) {                         // biometric prompt here
            is PayFlow.Signed.Ok -> showQr(s.record.framed)        // "PORTAGE:…" for the payee to scan
            PayFlow.Signed.Cancelled -> Unit                       // nothing was signed
            else -> explain(s)
        }
    }
    is PayFlow.QuoteResult.TierUnavailable -> explainTiers(q.options)
    PayFlow.QuoteResult.AmountRequired -> askForAmount()
    PayFlow.QuoteResult.ClockBlocked -> askToFixClock()
}

For vault-backed (T1/T2) and reserved (T3) payments, also pass a VoucherIssuer and a ReservedIssuer to PayFlow, and the vault and reservation stores to ReceiveFlow. Without them, the flows handle direct (T0) payments only.

4. Settle in the background

val queue = SettlementQueue(
    registry, network, store = db, chain = rpc,             // ChainPort: reads at `finalized`
    relayers = { listOf(relayer) },                          // tried in order, with backoff
    time = time, clock = clock,
)

// From WorkManager when online, and on app start:
val summary = queue.runOnce()
// summary.settled, summary.expired, summary.selfSubmittable (payments the user can settle with own gas)

rpc and relayer are your implementations of ChainPort and RelayerPort. The app's JSON-RPC and HTTP clients will ship as SDK adapters Coming Soon.

Ports you provide

Each flow takes the ports it needs in its constructor. Implement them yourself, or use the Android modules that already implement them.

Flows

Each flow is a class with suspend functions and sealed result types. None of them shows UI; each returns what your screens need.

Paying and receiving offline

1. Request. The payee's ReceiveFlow.newRequest returns a REQUEST (41–81 bytes) shown as a QR code. With Bluetooth it also carries an ephemeral X25519 key and an advertising tag.
2. Quote. PayFlow.quote lists every tier with its fee and expiry, vault tier first, and says why any tier is blocked.
3. Sign. PayFlow.sign asks for the fingerprint or PIN, with the amount and payee shown in the system prompt itself.
4. Verify, then store. ReceiveFlow.accept checks signature, payee, expiry, snapshot, the expiry rule and the receiver's limits, and stores the payment only if it passes.
5. Settle. SettlementQueue.runOnce submits to relayers and reads the outcome from the chain at finalized, never from the relayer.

Funding the offline balance

FundingFlow.quote(amount) returns the relayer's deposit fee or why funding is not possible now. fund(amount, fee, unlockDelaySec) creates the voucher key on first use, predicts the vault address locally, and signs one deposit authorisation. The relayer deploys the vault and deposits in one transaction. refresh() reports Done only when the deposit is visible at finalized.

Issuing a voucher safely

Vault lifecycle

The withdrawal delay is what protects receivers, so it cannot be skipped. A withdrawal rotates to a new voucher key and starts a new epoch. After a restore from the recovery phrase, RestoreFlow.discover() finds the vault from the chain alone and guides the user through this same unlock.

Carrying payments for others

Sync

SyncFlow.run() runs whenever the app is online and in the foreground, and daily in the background. Each step is independent, so one failure does not stop the others:

• chain time at finalized, recorded for the clock guard;
• the user's own vault state, read directly from the chain;
• an attested snapshot, verified against the attestor key pinned in the registry;
• vaults of recent counterparties, for checking their vouchers offline;
• the signed fee schedule, the signed deny-list of slashed vaults, and the main balance.

Fraud evidence and claims

When a received voucher fails because the vault could not pay, FraudFlow.run() checks for a fraud pair locally and through the relayer's evidence exchange. Once the payer's vault is slashed, it asks a relayer for the claim step that is due (file, settle, collect) and marks the payment CLAIMED when the chain shows the payout.

Payment states

Sent payments use OutboundState: SIGNING → ISSUED → SETTLED, EXPIRED or FAILED. HANDED_OFF marks a received payment given to a courier. Reminders.due(…) tells you when to notify the user 24 and 6 hours before a pending payment's deadline.

API reference Preview

Package org.portage.sdk. Every flow is safe to call from a coroutine; signing functions suspend while the user authenticates.

TypeScript developers can use @portage/protocol (encode, decode, verifyInbound, EIP-712 helpers, fraud proofs) from the repository today; an npm release is Coming Soon.

Wire format

Messages are binary. As text, for QR codes, they are the prefix PORTAGE: followed by Base45 (RFC 9285), which fits QR alphanumeric mode. Over Bluetooth and HTTPS the raw bytes are sent. Every message starts with a 4-byte header:

Decoders reject an unknown version or type, check the exact length before reading any field, and reject trailing bytes. Wallets built on the SDK interoperate by default; an integrator may restrict what it accepts by policy but must not change the format under the same version.

Error codes

Stable identifiers. Map each to a sentence the receiver can read to the payer.

Relayer and attestor

Both services are thin and replaceable. Neither holds user funds or keys. The app accepts a list of relayers and a set of attestors, and works with none of them if the user has gas. Both limit each client address to 120 requests a minute (answered 429 RATE_LIMITED).

Relayer · https://relay.portagewallet.xyz Live on Fuji

Statuses: QUEUED, SUBMITTED, INCLUDED, FINALIZED, REJECTED(code), REVERTED(reason), EXPIRED. A relayer's answer is advice; the SDK reads settlement from the chain.

curl https://relay.portagewallet.xyz/v1/health
curl https://relay.portagewallet.xyz/v1/fees/2

Attestor · https://attest.portagewallet.xyz Live on Fuji

Attestor answers are untrusted until verified: the SDK checks every signature against the attestor keys pinned in the registry. Mainnet will use three attestors with a two-of-three threshold Coming Soon. Self-hosting images for both services are Coming Soon.

Networks and contracts

Fuji deployment

Source is verified on Snowtrace. The contracts have no owner, admin, pauser, upgrade path or fee switch. The SDK ships these addresses in its registry; nothing about them is configured at runtime.

Integrator rules

Building on the SDK means keeping the promises it makes to users. These are conditions of use, not suggestions.

Security model

• Keys stay on the device. The owner key is encrypted under a keystore key that needs user authentication on every use; the voucher key is generated in secure hardware and cannot be exported.
• The contract is the enforcement point. Limits that matter live in the vault: the per-payment cap, the withdrawal delay, and the epoch rules. App limits protect the user only.
• Hostile input. Every decoder checks length first and rejects unknown versions, types and trailing bytes; nothing is allocated from an attacker-supplied length.
• Crash safety. Issuance is reserve → sign → commit, so a crash never reuses a sequence number.
• Clock safety. TimeGuard refuses to sign or accept after the clock was set back, and uses chain time when the device clock is far off.
• Audit. An independent audit, bug bounty and penetration tests come before mainnet Coming Soon.

Roadmap

1. Direct paymentsT0 payments, relayer, Android app foundation.
2. Offline vaultVouchers (T1), attestor, rescue mode; two phones paid offline and settled on Fuji.
3. Assurance and reach · nowBonds and fraud proofs (T2), reservations (T3), Bluetooth, carrying; public testnet beta.
4. Hardening and pilot Coming SoonAudit, three attestors, device attestation, NFC and SMS, mainnet, a first field pilot.
5. SDK and more chains Coming SoonThe portage-android package, npm 1.0, sample app, conformance suite, self-hosting images, a second chain and token, iOS.

Support

Follow progress and reach the team on X @Portagewallet. Try the wallet itself from the download page.