tane/docs/design/plantare-bilateral.md

Plantaré — the bilateral signed record

Status: v1 shipped (2026-07-14). The two-sided signed Plantaré — the "formulario bilateral firmado" other docs waited on — is now built end-to-end: transport in commons_core, schema v12 + repo, PlantareService, and UI (propose from a chat, accept/decline on the ledger). What's left is noted under "Deferred to a follow-up" below. This doc keeps the original design for reference; the "Open questions" are now resolved inline.

Built (commit series feat(plantare): …, 2026-07-14):

• Transport — PlantarePledge (canonical, byte-stable core + two BIP-340 Schnorr stubs), PlantareCrypto (sign/verify over SHA-256 of the core), PlantareTransport + NostrPlantareTransport (propose→accept→counter-sign / decline over NIP-17 gift wrap carrying a tagged JSON payload; the message inbox skips these and vice-versa).
• Schema v12 — the deferred columns on Plantares (pledgeId, debtorKey, creditorKey, debtorSignature, creditorSignature, movementId, remoteState, returnKind, workHours), all nullable/defaulted so v1 local rows are untouched; guarded migration + schema dump + migration test.
• PlantareService — signs my stub, sends, and reconciles incoming moves into the ledger (verifies stubs before storing; pending proposals held in memory keyed by pledge id, relay redelivers on reconnect).
• UI — propose sheet reached from the chat overflow menu; accept/decline + handshake badges (awaiting signature / signed by both / declined) on the Plantares screen.

This doc originally specified the two-sided Plantaré so a later session could build it without re-deciding. It is the "formulario bilateral firmado" that other docs wait on:

• data-model.md §2.7 — the Plantare entity, whose debtor_key, creditor_key, debtor_signature/creditor_signature and movement_id columns are specified there but deferred in the shipped Drift table.
• sharing-model.md §1, §6 — the Plantaré as the private bilateral close of an exchange; and the open question of anchoring reputation to a closed deal.
• PLAN.md §5-bis — the paper original (BAH-Semillero, 2009): "partida doble repartida entre dos bolsillos", device-to-device, provenance DAG.
• open-decisions.md — strong rating anchoring "espera al formulario bilateral firmado".

What ships today (v1, local-only)

A private local ledger only. apps/app_seeds Plantares table stores varietyId, direction (iReturn / owedToMe), counterparty (free text), owedDescription, madeOn, dueBy, status, note. No identity keys, no signatures, no transport — the other party gets no record. The UI now surfaces the linked variety and the dates (Phase 1), but it is still one-sided.

The paper original (v0.4, transcribed)

Source: BAH-Semillero, Plantaré — moneda comunitaria de intercambio de semilla, v4.0, © 2009–2010, CC-BY-SA 3.0 (plantare.ourproject.org). The printed form is two matching stubs ("partida doble") on one sheet:

Stub A — "CORTAR Y ENTREGAR A CAMBIO DE LAS SEMILLAS" (cut off and handed over with the seeds; the giver keeps it as proof of what they're owed):

• Yo ______ (your name)
• localizable en ______ (email, tel., etc. — contact info)
• recibo ______ (cantidad de semillas o lo que sea que recibo)
• y me comprometo a devolver antes de (mes/año): __ / 20__
• return options (choose those that apply):
  • [ ] una cantidad similar* de la recibida — (*) similar = no hibridada, no transgénica, cultivada en ecológico
  • [ ] ó un trabajo de ___ horas equivalente
  • [ ] ó ______ (free text — anything else)
• Firmado, ______ el __ / __ / 20__ (signature + date)

Stub B — "RESGUARDO QUE ME QUEDO" (the receipt the receiver keeps to remember what they owe): person/collective owed, quantity received, and "lo devolveré antes de /20".

What the paper captures that v1 does not yet:

• Contact of the party ("localizable en") — v1 stores only a free-text name. Digitally this becomes the Nostr pubkey (reachable by DM); keep a free-text contact for the offline/paper case.
• Structured return options instead of one free-text line: similar quantity (default), equivalent work in N hours, or other. The work-hours option is time-as-currency — it overlaps Tane's hand-over payment model, which already allows a time/tiempo currency ([project-sales]; €/Ğ1/time/none).
• "Similar" is a defined term — open-pollinated, non-GMO, organically grown — which ties to Tane's existing organic/eco self-declaration flag. The default return preset should carry this meaning, not just the word.
• Return-by is month/year, matched to cultivation cycles (v1 stores a full day; Phase 1's picker is day-precision — display can round to month/year).

The goal

Turn the one-sided note into the paper Plantaré's two matching signed stubs: when two people close an exchange, both devices end up holding the same commitment, each signed by both, so either can prove "recibí X, devolveré una cantidad similar antes de la fecha Y".

Non-goals: interest, enforcement, debt framing (microcopy stays "promise, not debt"); a central server or global ledger (it stays device-to-device / relay-as-enrichment).

Identity — counterparty becomes a real key

Replace (or rather, augment) the free-text counterparty with the counterparty's Nostr pubkey / Party, reusing the identity already present in the social layer (offers, chat). The flow starts from an existing conversation or a closed offer, so the pubkey is in hand. Keep the free-text field as the offline/paper fallback (a Plantaré made face-to-face with someone who has no app, or ingested from a paper form / QR).

Schema delta (versioned Drift migration)

Add the deferred columns to Plantares, nullable so v1 rows coexist untouched:

• debtorKey TEXT — pubkey of who received and owes a return.
• creditorKey TEXT — pubkey of who gave.
• debtorSignature / creditorSignature TEXT — signatures over the canonical payload (both "stubs of the paper").
• movementId TEXT → Movement — the shared given event this accompanies (the Movement.plantareId link already exists on the other side).
• remoteState enum — proposed / accepted / declined, distinct from status (open/returned/forgiven), which tracks the promise, not the handshake.

From the paper form:

• contact (the paper's "localizable en", email/phone) — decided NOT needed (2026-07-13). It's a paper-era artifact: digitally the counterparty is a Nostr pubkey, reachable by DM, so a manual contact field is redundant. Offline/paper Plantarés keep it only inside the free-text counterparty.
• returnKind enum — similar / workHours / other, mirroring the form's checkboxes (default similar, meaning open-pollinated · non-GMO · organically grown — surface that definition, not just the word). workHours REAL for the "trabajo de N horas" option; owedDescription still backs other. Note the work-hours option overlaps Tane's hand-over time/tiempo currency — reconcile the two rather than duplicating. Kept for the Phase 2 build; not added to v1.

A v1 local row = both keys/signatures null, remoteState null. Migration test in CI per data-model.md §5.

Transport — PlantareTransport in commons_core

A new interface alongside OfferTransport / MessageTransport / TrustTransport / RatingTransport / SyncTransport / ReportTransport (packages/commons_core/lib/src/social/), on the shared NostrConnection. Unlike ratings (public signed events), a Plantaré is private to the two parties, so it is encrypted, like DMs/sync. Sketch, mirroring the existing *Transport shape:

abstract interface class PlantareTransport {
  /// Send a signed proposal (my signature only) to [counterpartyPubkey].
  Future<void> propose(PlantarePledge pledge);
  /// Counter-sign a received proposal and send the fully-signed copy back.
  Future<void> accept(PlantarePledge pledge);
  /// Decline a received proposal.
  Future<void> decline({required String pledgeId, String reason});
  /// Incoming proposals / accepts / declines addressed to this identity.
  Stream<PlantareEnvelope> incoming();
  Future<void> close();
}

Handshake: propose → accept → counter-sign. A proposes (signs, encrypts to B); B reviews, accepts (adds B's signature), sends the doubly-signed copy back; both persist the identical row (remoteState = accepted). Decline leaves A's row declined.

Channel: prefer NIP-17 encrypted DM (already used for messaging) carrying a canonical JSON payload — least new surface, rides the existing connection. A dedicated event kind is an alternative if we want first-class filtering. Offline QR/NFC device-to-device (PLAN.md's favoured, most-decentralized path) is the same payload exchanged without a relay — the transport abstracts channel from payload. Relays are enrichment only; offline must fully work.

Provenance DAG

Each accepted Plantaré links parent→child (this lot came from that exchange), forming the variety's distributed procedence DAG (PLAN.md §5-bis) — "un grafo de commits, pero de semillas". movementId + the counterparty's prior movement give the edge.

Reputation anchor

An accepted Plantaré is the strong anchor for a rating (both parties provably closed a real deal), upgrading the current soft, per-conversation anchoring — closing the open-decisions.md / network-trust.md item.

Resolved in the v1 build (2026-07-14)

• Conflict / divergence: RESOLVED as anticipated — the two signatures cover the canonical core (everything except the signatures), and the pledgeId is part of that core. Any edit changes the signing hash, so an accept always closes the exact payload proposed; a changed pledge is a different id and must be re-proposed. PlantareCrypto enforces this; the "editing after signing invalidates the stub" test pins it.
• Revocation / forgiveness sync: kept one-sided for v1 — status (open/returned/forgiven) stays each party's own view, distinct from the shared remoteState handshake. Propagating a forgive to the counterparty is a follow-up (it'd need a signed "released" move).
• Expiry: dueBy passing is a UI nudge only (overdue styling), as in Phase 1 — it does not change remoteState.
• Paper ingest: the schema already supports it (nullable keys/signatures + free-text counterparty); no UI path yet — deferred.
• Group/collective party: deferred — still tied to the collective-identity question in sharing-model.md §6.

Deferred to a follow-up

• Durable send outbox. Propose/accept send best-effort over the current session; if offline the local row is recorded but the move isn't queued for retry. A durable outbox (like offer_outbox) should back it so a proposal made offline goes out on reconnect.
• Accept after restart before redelivery. Pending proposals live in memory (refilled by NIP-17 redelivery on reconnect); accepting one the relay hasn't redelivered yet shows a gentle "offline / reconnecting" nudge rather than reconstructing the pledge from the row.
• Rating anchor. An accepted Plantaré is now a provable closed deal, but the rating flow isn't yet wired to require/prefer it (the "strong anchor" upgrade).
• Provenance DAG. movementId is stored; building the distributed procedence graph from accepted pledges is not done.
• Forgiveness/paper/group as above.