Confirmar un pago
El aparato le pregunta a un nodo de Stellar RPC por los pagos que entraron a una cuenta y lee, él mismo, cuánto llegó y con qué número de pedido. Es la base de un torniquete, un dispensador o una caja: cuando llega el pago esperado, se activa lo que haga falta.
Para esto el aparato no necesita ninguna llave: solo lee de la red.
Los fragmentos de esta guía salen de examples/esp32_standalone_device, el ejemplo del
repositorio con un aparato autónomo que cobra así. La función completa está al
final de la página.
Cómo se ve un pago en la red
Sección titulada «Cómo se ve un pago en la red»Cada pago queda en la red como un evento transfer del contrato del token, con quién pagó, quién
recibió y el monto. Eso vale para los pagos comunes y para las llamadas a contratos: un mismo
filtro los encuentra a los dos.
El aparato pide con getEvents los transfer de un contrato hacia una cuenta, desde un
ledger en adelante.
1. El contrato del token
Sección titulada «1. El contrato del token»El contrato se calcula en el aparato, a partir de la red y del activo:
mcu_sha256((const uint8_t *)NETWORK, strlen(NETWORK), g_network_id);stl_asset xlm = {true, "", {0}};stl_asset_contract(&CRYPTO, g_network_id, &xlm, g_contract);
char contract_text[57];stl_addr_encode(STL_ADDR_CONTRACT, g_contract, contract_text); // C...Filtrar por esa dirección evita aceptar un token falso con el mismo nombre.
| Activo | Contrato en testnet |
|---|---|
| XLM | CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC |
| USDC | CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA |
2. El filtro
Sección titulada «2. El filtro»El filtro lleva dos temas: el nombre del evento y la cuenta que recibe.
char topic_transfer[32], topic_me[72];uint8_t buf[64];size_t n = stl_scval_symbol(buf, sizeof buf, "transfer");stl_b64_encode(buf, n, topic_transfer, sizeof topic_transfer);n = stl_scval_account(buf, g_public);stl_b64_encode(buf, n, topic_me, sizeof topic_me);
snprintf(stellar_rpc::params(), stellar_rpc::paramsCap(), "{\"startLedger\":%lld,\"filters\":[{\"type\":\"contract\",\"contractIds\":[\"%s\"]," "\"topics\":[[\"%s\",\"*\",\"%s\",\"**\"]]}],\"pagination\":{\"limit\":5}}", (long long)from_ledger, contract_text, topic_transfer, topic_me);stellar_rpc::call("getEvents", stellar_rpc::params());El * del medio deja pasar a cualquier pagador. from_ledger es desde cuándo se vigila: el
ledger en que se creó el cobro, que da getHealth en latestLedger.
3. Leer el monto y el número de pedido
Sección titulada «3. Leer el monto y el número de pedido»Cada evento trae su valor en base64. stl_event_amount saca el monto y, si lo hay, el memo:
uint8_t raw[160];bool has_memo = false;uint64_t memo = 0;field = stl_json_string(event, "value", &n);int bytes = field ? stl_b64_decode(field, n, raw, sizeof raw) : -1;if (bytes <= 0 || !stl_event_amount(raw, (size_t)bytes, &in->amount, &has_memo, &memo)) continue;El valor llega en dos formatos según el pago, y la función lee los dos:
| Pago | Cómo llega el valor |
|---|---|
| Llamada al contrato del token | El monto solo. |
| Pago común con memo | El monto y el memo juntos. |
4. Saber qué pago es de qué venta
Sección titulada «4. Saber qué pago es de qué venta»Dos clientes pueden pagar casi a la vez. Para no confundirlos:
- Un número de pedido por cobro. Cada cobro lleva un número distinto en el memo del
pedido de pago, y
stl_event_amountlo devuelve: el pago que llega con ese número es el de esa venta. El ejemploesp32_pay_and_confirmpaga con el pedido 4242 y lo vuelve a leer en el evento. - Sin memo, se compara el monto y que el evento sea posterior al cobro. Es lo que hace el aparato autónomo: da por pagado el primer evento nuevo que alcance el monto.
5. No contar dos veces
Sección titulada «5. No contar dos veces»Cada evento tiene un identificador, y los identificadores crecen con el tiempo. Guarda el último que ya contaste y descarta los que no sean mayores:
char id[40] = "";const char *field = stl_json_string(event, "id", &n);if (!field || n >= sizeof id) continue;memcpy(id, field, n);if (strcmp(id, g_last_event_id) <= 0) continue; // already countedstrcpy(g_last_event_id, id); // counted from now on, whatever its amountPara que un corte de luz no haga contar un pago dos veces, guarda ese identificador en la memoria del microcontrolador.
Lo que conviene saber
Sección titulada «Lo que conviene saber»- El nodo guarda unos 7 días de eventos. Es para confirmar cobros, no para llevar un historial.
- Los pagos comunes aparecen como eventos si el nodo los emite. El nodo de testnet de la Stellar Development Foundation lo hace. Con otro proveedor, confírmalo.
- Una respuesta con dos eventos pesa 1,4 KB. El límite de eventos por consulta la mantiene dentro del búfer.
La función completa
Sección titulada «La función completa»Así busca el pago el aparato autónomo. Es parte de
examples/esp32_standalone_device/src/main.cpp, en el
repositorio:
// Looks in the XLM contract's events for a "transfer" to the device of at least `min_amount`, newer// than the ones already counted. Remembers who paid.static bool find_incoming(int64_t from_ledger, int64_t min_amount, Incoming *in) { char contract_text[57], topic_transfer[32], topic_me[72]; uint8_t buf[64]; stl_addr_encode(STL_ADDR_CONTRACT, g_contract, contract_text); size_t n = stl_scval_symbol(buf, sizeof buf, "transfer"); stl_b64_encode(buf, n, topic_transfer, sizeof topic_transfer); n = stl_scval_account(buf, g_public); stl_b64_encode(buf, n, topic_me, sizeof topic_me); snprintf(stellar_rpc::params(), stellar_rpc::paramsCap(), "{\"startLedger\":%lld,\"filters\":[{\"type\":\"contract\",\"contractIds\":[\"%s\"]," "\"topics\":[[\"%s\",\"*\",\"%s\",\"**\"]]}],\"pagination\":{\"limit\":5}}", (long long)from_ledger, contract_text, topic_transfer, topic_me); if (!stellar_rpc::call("getEvents", stellar_rpc::params())) return false;
// Each event starts with {"type": ; they are checked one by one in a copy. const char *p = strstr(stellar_rpc::body(), "{\"type\":"); while (p) { const char *next = strstr(p + 8, "{\"type\":"); static char event[1400]; size_t len = next ? (size_t)(next - p) : strlen(p); if (len >= sizeof event) len = sizeof event - 1; memcpy(event, p, len); event[len] = 0; p = next;
char id[40] = ""; const char *field = stl_json_string(event, "id", &n); if (!field || n >= sizeof id) continue; memcpy(id, field, n); if (strcmp(id, g_last_event_id) <= 0) continue; // already counted strcpy(g_last_event_id, id); // counted from now on, whatever its amount
uint8_t raw[160]; bool has_memo = false; uint64_t memo = 0; field = stl_json_string(event, "value", &n); int bytes = field ? stl_b64_decode(field, n, raw, sizeof raw) : -1; if (bytes <= 0 || !stl_event_amount(raw, (size_t)bytes, &in->amount, &has_memo, &memo)) continue; if (in->amount < min_amount) { Serial.println("A payment smaller than the charge arrived: it does not count"); continue; } field = stl_json_string(event, "txHash", &n); snprintf(in->tx, sizeof in->tx, "%.*s", field ? (int)n : 0, field ? field : "");
// Who paid: the second topic is the sender's address. g_has_payer = false; const char *topics = strstr(event, "\"topic\":[\""); const char *second = topics ? strstr(topics + 10, "\",\"") : NULL; const char *end = second ? strchr(second + 3, '"') : NULL; if (end && stl_b64_decode(second + 3, (size_t)(end - second - 3), raw, sizeof raw) == 44 && raw[3] == 18 && raw[7] == 0) { // an account (G...), not a contract memcpy(g_last_payer, raw + 12, 32); g_has_payer = true; } return true; } return false;}El mismo recorrido, con el mismo núcleo, está probado contra testnet: detectó la carga inicial de una cuenta y un pago de 1,5 XLM con el pedido 4242 (transacción 42fc3542…94af).