Introducción para desarrolladores de PHP

De Bitcoin Wiki
Saltar a: navegación, buscar

En esta introducción, asumiremos que se trabaja con un servidor GNU/Linux con Apache y PHP y que se desea interactuar con la red Bitcoin desde una aplicación web. Se presuponen conocimientos de Bitcoin y experiencia en PHP.

Aun cuando esta introducción está escrita para PHP, en otros lenguajes se pueden aplicar los mismos principios con los cambios típicos de sintaxis. Véase la página de la referencia API para la información sobre otros lenguajes.

La manera más sencilla de comenzar consiste en ejecutar Bitcoin en modo demonio (daemon), mediante el ejecutable básico bitcoind con el que PHP se comunicará mediante peticiones locales HTTP. Para llamar a las diversas funciones que ofrece bitcoind se utiliza una biblioteca llamada JSON-RPC, que devuelve el valor de retorno en forma de un objeto JSON.

Cómo configurar Bitcoin

Puede descargar el demonio Bitcoin desde la página principal. Es uno de los archivos binarios incluidos en el paquete de instalación (bitcoind.exe). También es posible compilarlo a partir del código fuente. Véase Ejecutando Bitcoin para más información sobre cómo configurar bitcoind.

Antes de ejecutar bitcoind necesitará crear un archivo de configuración en el directorio de datos de Bitcoin (~/.bitcoin/bitcoin.conf en Linux):

rpcuser=usuario
rpcpassword={DEBE elegir una contraseña confidencial y única por seguridad}

Si se omite este paso, bitcoind se lo recordará.

Ejecute ahora bitcoind:

$ ./bitcoind
# espere unos segundos a que se inicie
$ ./bitcoind getinfo
# se mostrará información variada. Si ocurre un error, vuelva a intentarlo.
$ ./bitcoind help
# ayuda sobre las funciones o comandos, nótese que no se escribe guion delante de "help"

Bitcoin comenzará entonces a sincronizarse con la red descargando una copia completa de la cadena de bloques. En agosto de 2012, son más de 2 GB de datos los que se han de descargar y verificar durante este proceso, que puede llevar incluso más de dos horas. Sabrá cuando ha concluido porque el número de bloques alcanzará el valor actual.

Getinfo (El "Hello World" de bitcoind)

Una vez que Bitcoin ha completado el proceso de inicialización, descargue el archivo jsonRPCClient.php de JSON-RPC PHP y cópielo a una ubicación accesible al código web.

En segundo lugar, cree un archivo PHP con el contenido siguiente y ábralo con su navegador web para probarlo.

  require_once 'jsonRPCClient.php';
 
  $bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');
 
  echo "<pre>\n";
  print_r($bitcoin->getinfo());
  echo "</pre>";

Precisión

Las cantidades Bitcoin admiten un rango entre 1 (0,00000001 BTC, la unidad mínima monetaria coloquialmente conocida como satoshi) hasta casi 2.100.000.000.000.000 (21.000.000 BTC, el límite superior de la cantidad total de unidades que pueden llegar a existir). Para evitar errores de redondeo, debe asegurarse de que su implementación de PHP admite el rango completo de cantidades Bitcoin sin pérdida de precisión. La mayoría de implementaciones de PHP utilizan números de coma flotante de precisión doble IEEE de 64 bits con 53 bits de precisión, que es suficiente para la representación correcta del rango completo de valores Bitcoin.

Véase Gestión correcta de unidades monetarias (JSON-RPC) para más información.

Si su implementación de PHP no admite números de 64 bits (que, insistimos, sería extremadamente raro), deberá utilizar una versión de bitcoind que envíe los valores como cadenas de texto (el desarrollador genjix mantiene un fork en http://github.com/genjix/bitcoin) y utilizar las bibliotecas GMP y BC Math para todo cálculo que implique cantidades Bitcoin.

Cuentas

En Bitcoin, las cantidades monetarias se envían a direcciones. Estas direcciones se almacenan en un monedero. El saldo mostrado por defecto en bitcoind es la suma de los bitcoins en todas las direcciones del monedero.

Nótese que el concepto de "dirección" se utiliza en el nivel de protocolo, mientras que el concepto de "monedero" como colección de direcciones es una abstracción de más alto nivel que introduce el propio programa cliente bitcoind. El programa cliente bitcoind tiene también el concepto de cuentas. Cada cuenta es una agrupación de direcciones, un subconjunto del monedero.

$ ./bitcoind listaccounts
# muestra la lista de cuentas e información variada sobre cada una
$ ./bitcoind getaccountaddress usuario889
# obtiene una dirección en la que recibir dinero que es única para la cuenta usuario889
$ ./bitcoind getbalance user889
# obtiene la suma de todos los bitcoins en las direcciones que pertenecen a la cuenta usuario889

En su aplicación, cada usuario debería tener un nombre de usuario único. De esa manera, podrá solicitar a bitcoind una dirección única mediante la llamada "$bitcoin->getaccountaddress("usuario889");", que retorna la primera dirección de usuario889, o "$bitcoin->getnewaddress("usuario889");", que crea una nueva dirección para usuario889.

De esta manera, se consigue que el usuario en el mundo real pueda hacer pagos a una dirección particular suya.

Puede comprobar el saldo del que dispone este usuario mediante la llamada "$bitcoin->getbalance("usuario889", 4);". El valor 4 indica el número mínimo de confirmaciones que exigimos para dar los pagos por válidos.

Si tiene la intención de utilizar cuentas para depósitos y extracciones múltiples a largo plazo, debería plantearse apuntar los saldos de los usuarios en su propia base de datos. Esto simplificará las transferencias entre las cuentas de su aplicación y desacoplará sus cuentas de usuario del monedero Bitcoin.

getnewaddress frente a getaccountaddress

Al utilizar getnewaddress, se preserva mejor el anonimato de sus usuarios, ya que se dificulta la posibilidad de espiar con fines maliciosos los pagos que pasan por su aplicación. No obstante, si se ejecuta getnewaddress con demasiada frecuencia, esto hará que el monedero se llene de muchas direcciones vacías.

Se recomienda por ello limitar de alguna manera el número de direcciones vacías que pueda solicitar cada usuario. He aquí un ejemplo utilizando sesiones:

<?php
    require_once('jsonRPCClient.php');
    $bitcoin = new jsonRPCClient('http://root:root@127.0.0.1:8332/'); 
    # now check for appropriate funds in user account
    try {
        $username = ...
        if(isset($_SESSION['sendaddress']))
            $sendaddress = $_SESSION['sendaddress'];
        else {
            $sendaddress = $bitcoin->getnewaddress($username);
            $_SESSION['sendaddress'] = $sendaddress;
        }
        $balance = $bitcoin->getbalance($username);
    }
    catch (Exception $e) {
        die("<p>Server error! Please contact the admin.</p>");
    }
?>

El código anterior crea una dirección nueva al principio de cada sesión y lo almacena en la variable de sesión.

Véase también