Ir al contenido

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.

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.

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

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.

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.

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_amount lo devuelve. El aparato autónomo le pone un número a cada cobro y, si el pago trae un número, lo cuenta solo cuando es el suyo:

    if (has_memo && memo != order) {
    Serial.printf("A payment for order %llu arrived: it is not this charge\n", (unsigned long long)memo);
    continue;
    }
  • Sin memo, se compara el monto y que el evento sea posterior al cobro: el aparato autónomo da por pagado el primer evento nuevo que alcance el monto.

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 counted
strcpy(g_last_event_id, id); // counted from now on, whatever its amount

Para que un corte de luz no haga contar un pago dos veces, guarda ese identificador en la memoria del microcontrolador.

  • 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.

Así busca el pago el aparato autónomo. Es parte de examples/esp32_standalone_device/src/main.cpp, en el repositorio:

examples/esp32_standalone_device/src/main.cpp
// Looks in the XLM contract's events for a "transfer" to the device of at least `min_amount`, newer
// than the ones already counted. A payment that carries an order number (a numeric memo) counts
// only if it is `order`; one with no order number counts by its amount. Remembers who paid.
static bool find_incoming(int64_t from_ledger, int64_t min_amount, uint64_t order, 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 (has_memo && memo != order) {
Serial.printf("A payment for order %llu arrived: it is not this charge\n", (unsigned long long)memo);
continue;
}
if (in->amount < min_amount) {
Serial.println("A payment smaller than the charge arrived: it does not count");
continue;
}
in->by_order = has_memo;
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).