PrimeNet v5.0 Server Web API

Mersenne.org Research Projects

  • Great Internet Mersenne Prime Search

  • (others TDB)

RELEASE CANDIDATE VERSION 0.97(c)

Kurowski/Woltman 11/14/2007 RELEASE CANDIDATE 0.97(c)
Kurowski/Woltman 08/06/2007 RELEASE CANDIDATE 0.97(b)
Kurowski/Woltman 06/19/2007 RELEASE CANDIDATE 0.97(a)
Kurowski/Woltman 03/20/2007 DRAFT 0.96(g)
Kurowski/Woltman 03/28/2006 DRAFT 0.96(f)
Kurowski/Woltman 03/15/2006 DRAFT 0.96(e)
Kurowski/Woltman 01/21/2006 DRAFT 0.96(d)
Kurowski/Woltman 12/27/2005 DRAFT 0.96(c)

 

Kurowski/Woltman 11/20/2005 DRAFT 0.96(b)
Kurowski/Woltman 11/01/2005 DRAFT 0.96(a)
Kurowski/Woltman 09/28/2005 DRAFT 0.95
Kurowski/Woltman 09/27/2005 DRAFT 0.9
Kurowski/Woltman 09/17/2005 DRAFT 0.8
S. Kurowski 09/13/2005 DRAFT 0.7
S. Kurowski 09/09/2005 DRAFT 0.6
S. Kurowski 01/13/2004 DRAFT 0.5
S. Kurowski 01/01/2004 DRAFT 0.1

Contents

1.0 Web Interface API Description
2.0 Parameter Data Types
3.0 Safety Controls
4.0 Featured API Services
5.0 PrimeNet v5 Web Interface API Reference
6.0 PrimeNet v5 API Result Error Codes
7.0 Assignment Work Types
8.0 Assignment Result Types

1.0 Web Interface API Description

The PrimeNet Server web interface API for Mersenne.org application clients is a general purpose, concise, lightweight set of transactional HTTP web methods to automatically and centrally coordinate GIMPS and related project test execution across a set of Internet connected computers running client software implementations of the API. The web interface is specifically designed to support GIMPS and the easy addition of new client programs, platforms and work assignment types.

1.1 HTTP CGI GET Interface

The web interface API responds to each parameterized HTTP 1.1 GET method request with a simple new-line-delimited token-value paired text page. Each response page begins with an error result code and error detail reason. If the error code indicates success, the error detail is empty. The sentinel string "=END=\n\n" appears at the end of each complete response page.

Example CGI GET request:
http://v5.mersenne.org/v5/? px=GIMPS&v=0.97&t=ga&g=3874DFD725BA434082259AA25EA0BE5F&w=101&ss=&sh=

            ... and its example response web page:

HTTP/1.1 200 OK\r\n
(possibly other HTTP headers)
Content-Type: text/html\r\n\r\n
pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
p=421423411\n
w=101\n
k=29AA55BA874DFD724340825EA0BE325F\n
b=77\n
B1=542341\n
B2=12432321\n
cr=341227
=END=\n\n

The various API transactions respond with different token-value pairs. All GET parameter values and response page token-value pairs are encoded in simple, well-formed string formats. Null values are passed as empty strings. Quoted strings are not accepted.  Content-Type will be text/html for the CGI method API. Multiple applications may be concurrently supported, each having specific pre-defined application-specific request and response parameter requirements.

Client program API implementations should take special care to parse the response page to identify and extract SPECIFIC EXPECTED TOKENS and their values to avoid accidentally parsing HTTP headers or intercepting proxy/firewall response page content as server response values. With the exception of the error response values, the ordered sequence of response tokens should not be relied upon. The pnErrorDetail error details message is at most 4095 bytes long, but is usually much shorter.

All transactions complete successfully or fail with an error. Only upon success does the server commit the work of the transaction. If an error is returned, the client is responsible for performing the appropriate response or actions described in the API Notes for each transaction and in the API result error code descriptions.

1.2 Common API Error Codes

See 6.0 API Result Error Codes for a complete list of response conditions.  General errors that may be returned for any API transaction include:

2.0 Parameter Data Types

Elementary data types and precisions are expected and returned by the API. All data types have character set and length constraints (minima and maxima) determined by type, API requirements, or both.

Data Type

Max Precision

Comment

integer

32 bits decimal-encoded

unsigned; other/future API versions may be 64 bits

float

8 digits including decimal point

seldom is more than a few decimal places required

guid

32 hex digits; no leading 0x

unsigned 128 bits

string

parameter-dependent
(subject to minimum length,
maximum length,
null,
or other character set constraints)

Strings are not case-sensitive;
Strings must URL-encode white space and other escaped characters in %xx format;
Unencoded length may not exceed the max parameter length;
For non-message identifiers such as userIDs ('A'-'Z', 'a'-'z', '0'-'9', '_', '-') are considered valid characters;
Send null values as empty strings;
Do not quote-enclose strings;
Response pages do not have encoded white space or escape characters.

3.0 Safety Controls

3.1 Safety Features

PrimeNet's Mersenne.org web server interface API may attempt to regulate a client application's server access if its interaction is unhealthy for the server or the GIMPS project.

Client programs may operate under trusted (closed) or untrusted (open) security levels.  Both require the program's major version and CPU data formats are pre-registered with PrimeNet administrators so the program and its patched builds will be able to interact with the server.

3.2 Trusted Client Programs

The vast majority of PrimeNet client programs will be trusted versions.  Trusted client programs are built by a responsible single developer or small team who warrants custodial control and private retention of a security source code module provided by the PrimeNet administrators to enable secure program interaction with the server. Trusted programs interact with the server during both high security and normal security states.

3.3 Untrusted Client Programs (Open Source)

Untrusted client programs are supported by this API. These programs are developed from downloadable open source and do not have a controlled security source code module. They can interact with the server only during a normal security state, and are permitted to run so long as they are well-behaved and productive.

In the event PrimeNet determines an untrusted program is operating counterproductively, first that individual program will be denied access. Failing that, or under conditions of a broader problem, PrimeNet enters a high-security state such that all untrusted programs are denied access. The security state may revert to normal once the problem is satisfactorily addressed.

4.0 Featured API Services

PrimeNet's web interface API has refactored and expanded capabilities relative to those provided by the legacy v4 GIMPS PrimeNet server, in addition to nominal base services for user accounting and CPU workflow management:

5.0 PrimeNet v5 Web Interface API Reference


5.1 uc - Update Computer Info

5.1.1 DESCRIPTION

Register, update or recover a computer program instance, and determine last options update.

5.1.2 COMMON PARAMETER DATA

5.1.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.1.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=uc
&g=3874DFD725BA434082259AA25EA0BE5F
&hg=B83CD3021F0A425EA0BE5F553C710D4A
&wg=025A34183CD3A4F0B5EA0710D2BE5F5
&a=Windows,%20Prime95,%20v25.1,%20build%201
&c=Intel%20P4-M
&f=RDTSC,CMOV,PREFETCH,MMX,SSE,SSE2
&L1=8
&L2=512
&np=2
&hp=0
&h=24
&m=2048
&s=2200
&r=2199
&u=challenge9912
&cn=SJK_6
&ss=3246792
&sh=183CFA034BE5D3A40B5E710D2F25A5

5.1.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
g=<guid>\n
u=<userID>\n
un=<public user name>\n
cn=<public CPU name>\n
od=<options_date>\n
=END=\n\n

5.1.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
g=3874DFD725BA434082259AA25EA0BE5F\n
u=challenge9912\n
un=Kurowski\n
cn=SJK_6\n
od=9\n
=END=\n\n

5.1.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.1.4 NOTES

  1. The 'uc' CPU/app info transaction may be sent as often as the client program wants, but it MUST be sent at least once before any assignment requests, updates or results, and PARTICULARLY after a change in CPU or software, including initial program installation. The server may eventually respond to other transactions with ERROR_STALE_CPU_INFO indicating the client MUST perform a 'uc' transaction before the server will allow the client to proceed.
     

  2. u (userID) MUST exist in advance on the server, or must be null. To bind a new computer g (guid) to an account, u (userID) must not be null.  Afterward, in routine use, u (userID) is null because g (guid) is sufficient to convey identity.

    If (u) is null and the computer's guid has not previously been registered at the server under a userID, the computer's guid is bound to the publicly-named ANONYMOUS userid. Subsequent transfer of the computer to another userid requires administrative action.
     

  3. The server populates the response page u (userid), un (public user name) and cn (public CPU name) values with accepted account u (userid), un (public user name) and cn (public CPU name) values associated with g (guid).
     

  4. New unique values of a (application version), c (CPU model) and f (CPU features) are self-registering in the server. Variants of CPU models and program builds may register and continue operating normally.

    However, as both a safety measure and a practical requirement for efficient assignment workflow, the a (application version) string MUST partially MATCH a pre-authorized value in order to be assigned work to do by the server, so arbitrary values may result in a client program being indefinitely idle.

    Similarly, c (CPU model) and f (CPU features) strings MUST partially MATCH pre-authorized values for the client program to be assigned work.
     

  5. The (u,g) values bind g (GUID) to its owning u (userID). The client program may change the binding at any time, automatically transferring all work assignments of that program with the transferred CPU to u (the new userID), by setting the o (original userID) value.
     

  6. Hardware ID hash (hg) and Windows hash ID (wg) are bound to the g (guid) at the server the first time guid (g) is given by a program. These values are client program-generated, hardware-derived 128-bit values in 32-digit hexadecimal format. After the initial registration call to the 'uc' interface, subsequent inclusion of hg or wg is optional, however the values must match the initial binding values or error ERROR_CPU_IDENTITY_MISMATCH is returned.

    If (g) is omitted the (hg) hardware ID hash is used to attempt a server lookup recovery of the guid (g), which if found is returned in the response, after which the client is expected to persist the guid for use in subsequent API transactions.  If no (g) value can be determined from the hardware ID hash (hg), the wg (windows GUID) is used to attempt a server lookup recovery of the guid (g).  If this fails, ERROR_UNREGISTERED_CPU is returned.
     

  7. cn (public CPU name) sets or updates the public CPU name. If cn is null an empty name is registered or updated.  The account owner may later change the name of the computer on the web site.  The response parameter cn (public CPU name) is set to the public name assigned to the CPU as recorded in the server.
     

  8. The response parameter un (public user name) is set to the public name assigned to the userID. This value is set only via the user's web site interaction when they create their userID.
     

  9. g (GUID) is a persistent, client program-generated random 128-bit value in 32-digit hexadecimal format. g (GUID) MUST be kept a machine-local 'semi-secret' value.
     

  10. od (options data counter) is returned in the response from the server to reflect the count of the server's registered options for this program were changed (see 'po' program options). It is up to the program to decide if it subsequently must perform a 'po' transaction to retrieve updated program options.
     

  11. ss (security salt) and sh (security hash) are used by all trusted programs. Untrusted programs must use null values for these parameters.  If the server API enters a high-security state, ERROR_ACCESS_DENIED will be reported for all programs not including valid ss and sh values. The ss, sh values must be the last parameters at the end of the URL, in that order.

5.1.5 APPLICATION-SPECIFIC PARAMETERS

None.


5.2 po - Program Options

5.2.1 DESCRIPTION

Get/set program options including work assignment preferences for each CPU on a computer.

The program initially decides a work assignment preference for each CPU from hardware capability and local user preference settings, and sends those to the server using 'po'.  However the server will also send back to the program preference options set by the user through their account management web pages, and where sensible and possible the program should accommodate those remotely configured preferences. Ultimately, the server decides what work assignments to send to the program using a combination of information such as preferences, available assignments, and CPU capabilities.

5.2.2 COMMON PARAMETER DATA

5.2.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.2.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=po
&g=3874DFD725BA434082259AA25EA0BE5F
&c=0
&w=101
$nw=1
&ss=
&sh=

5.2.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
<options_token1>=<options_value1>

...

<options_tokenN>=<options_valueN>
=END=\n\n

5.2.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
w=101\n
od=351\n
=END=\n\n

5.2.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.2.4 NOTES

  1. The 'po' transaction should be sent at least once prior to any assignment-related transactions to register or refresh the server's information about the assignment and other preferences for this computer.
     

  2. A preference order of precedence is observed. The server ultimately makes the final decision for what work type units are assigned, however the 'po' transaction provides a mechanism to establish a work type selection bias that usually satisfies both the client program's and the server's priorities.

    Example program work preference sequence:

    (a) program gets saved or new local user-specified or default preferences.
    (b) program sends those preferences to the server via the 'po' transaction API.
    (c) program receives the 'po' API response, so that it knows what the server is going to assign to it. In the absence of any overriding priorities set by the computer's owner using the web site, the server will save and use the preferences sent by the program.
    (d) each time the program initiates the 'po' API transaction, this sequence must be repeated.
     

  3. The 'po' transaction resets the counter returned by the od (options data) parameter in the uc (update_computer) transaction.  It is through the 'uc' interface that a program would first know the user has remotely changed CPU program options using their web management pages.
     

  4. ss (security salt) and sh (security hash) are used by all trusted programs. Untrusted programs must use null values for these parameters.  If the server API enters a high-security state, ERROR_ACCESS_DENIED will be reported for all programs not including valid ss and sh values. The ss, sh values must be the last parameters at the end of the URL, in that order.

5.2.5 APPLICATION-SPECIFIC PARAMETERS

5.2.5.1 GIMPS

5.2.5.1.1 GIMPS Request and Response Parameters

GIMPS-specific application request and response parameters labeled in 5.2.2.1 above as <options_token>=<options_value> token-value pairs are given in the table of permitted recognized tokens and values below.

options_token
(CASE SENSITIVE)

description

data_type
& constraints

permitted
options_values

Required

w

work_type preference

integer;
may be null

(see 7.3 GIMPS Work Preferences)

NO

nw

number of worker threads

integer

1 to 32

NO

Priority

Priority to run worker threads

integer

1 to 9

NO

DaysOfWork

Days of work client should queue locally

integer

1 to 90

NO

DayMemory

MB of memory prog can use in daytime

integer

 

NO

NightMemory

MB of memory prog can use at nighttime

integer


 

NO

DayStartTime

Minutes after midnight

integer


 

NO

NightStartTime

Minutes after midnight

integer


 

NO

RunOnBattery


True if worker threads should run when laptop is running on battery power 

integer

0 or 1

NO

5.2.5.1.2 GIMPS Notes

  1. The program options 'po' transaction sets and retrieves the same parameters. Setting a null value for a GIMPS-specific request parameter causes the server to skip updating that option. This mechanism allows a program to retrieve the server's registered preferences for this program without changing them.
     

  2. A full set of response parameters are returned by the server only when NO GIMPS-specific parameters are supplied.
     

  3. When parameter 'c' is given, the 'w' work_type preference parameter is associated specifically with that CPU worker thread. If 'c' is omitted, all CPU worker threads are updated to use the give work_type preference.
     

  4. When incremented, the response value of the 'od' parameter signals the client an options change was recorded by the server.


5.3 ga - Get Assignment

5.3.1 DESCRIPTION

Request a work assignment according to the program's registered CPU, software and options information.

5.3.2 COMMON PARAMETER DATA

5.3.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.3.2.2 Example Request

Request preferred work type assignment:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ga
&g=3874DFD725BA434082259AA25EA0BE5F
&c=0
&ss=
&sh=

Recover count of assignments for CPU 0:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ga
&g=3874DFD725BA434082259AA25EA0BE5F
&c=0
&a=0
&ss=
&sh=

Recover assignment number 1 for CPU 0:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ga
&g=3874DFD725BA434082259AA25EA0BE5F
&c=0
&a=1
&ss=
&sh=

5.3.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
k=<assignment_key_guid>\n
a=<number_of_assignments_for_cpu>\n
<work_unit_token1>=<work_unit_value1>\n
...
<work_unit_tokenN>=<work_unit_valueN>\n
=END=\n\n

5.3.2.4 Example Response

Assignment response or recovered assignment number 1 for CPU 0:

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
g=3874DFD725BA434082259AA25EA0BE5F\n
k=D7259AFD4BA5E5F434082EA0B72538A2\n
w=100\n
n=20214111
sf=72.0
p1=1
=END=\n\n

Recovered count of assignments for CPU 0:

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
g=3874DFD725BA434082259AA25EA0BE5F\n
a=2\n
=END=\n\n

5.3.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.3.4 NOTES

  1. The 'uc' transaction is generally sent immediately prior to any assignment-related transactions to register or refresh the server's information about the CPU and software.
     

  2. Any preferred work_type selection previously set using the 'po' transaction or via the server web site is taken into consideration by assignment algorithms, but does not guarantee that work_type will be assigned. If no preferred work_type selection has been made, the server will assign work according to CPU, program and workload need.
     

  3. It is the responsibility of the requesting client program to acquire as however much or little work assignments it may require to queue for expected periods of network unavailability to stay fully utilized during those periods.
     

  4. Assignments are initially issued to automatically expire within several minutes unless the requesting program immediately acknowledges receipt of the assignment by updating the server with 'ap' - assignment progress transaction having an intermediate progress status, estimated completion date, and estimated next progress update date.
     

  5. The response k (assignment key guid) is a work unit assignment handle required for future progress and results transactions.  The client program MUST reference k (assignment key) in all transactions having this parameter.
     

  6. When the parameter a (retrieve assignment by number for given cpu) is given, no new work assignment is given but rather a prior assignment is returned. Assignments are ordered in descending date order where the oldest is assignment 1, the next oldest 2 and the most recent assignment being the highest assignment number.

    It is important to leave the 'a' parameter NULL when requesting a new work unit assignment. Set a=0 to return no assignment yet receive a successful transaction response. The response a parameter a is the number of work unit assignments issued to the given cpu number. This interaction provides a work unit recovery feature for client programs.

5.3.5 APPLICATION-SPECIFIC PARAMETERS

5.3.5.1 GIMPS

5.3.5.1.1 GIMPS Request Parameters

None.

5.3.5.1.2 GIMPS Response Parameters

GIMPS-specific application response parameters labeled in 5.3.2.3 above as <work_unit_token1>=<work_unit_value1> token-value pairs are given in the table of permitted recognized tokens and values below.

work_unit_token
(CASE SENSITIVE)

description

data_type
& constraints

permitted
work_unit_values

a

assignment count
for CPU c

integer

use only for ga - get assignment

w

work_type

integer

(see 7.2 GIMPS Work Types)

B1

P-1/ECM lower bound

double

any positive integer

B2

P-1/ECM upper bound

double

any positive integer

CR

ECM curves run

integer

any 32 bit unsigned value

A

A in a*b^n+c

double

Any 53 bit positive integer

b

B in a*b^n+c

integer

Must be 2 in this release

n

exponent n in a*b^n+c

integer

Positive integer

C

C in a*b^n+c

integer

Signed value

sf

no factor to sf bits

float

0 <= sf < 100 (?)

ef

Client should factor to ef bits

float

ef > sf 

p1

Has been P-1 factored

integer

0 = not been P-1 factored, 1=has been P-1 factored

kf

comma separated list of known factors

string

 

saved

LL Tests saved if P-1 finds a factor

float


 

5.3.5.1.3 GIMPS Notes

  1. Response parameter w (work_type) is always returned by the server response except when input parameter a=0.
     

  2. All other response parameters are work_type-dependent and may not necessarily appear in the server's response.


5.4 ra - Register Assignment

5.4.1 DESCRIPTION

Register a work assignment by preferred work type and registered CPU and software information.

5.4.2 COMMON PARAMETER DATA

5.4.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.4.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ra
&g=3874DFD725BA434082259AA25EA0BE5F
&c=0
&w=101
&n=20996011
&ss=
&sh=

5.4.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
k=<assignment_key>\n
=END=\n\n

5.4.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
k=D7259AFD4BA5E5F434082EA0B72538A2\n
=END=\n\n

5.4.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.4.4 NOTES

  1. The 'ra' transaction opens an assignment but does NOT update the work assignment progress information. A successful response from this transaction issues an assignment key and puts the work unit into the same state as if the client program had successfully performed a 'ga' Get Assignment request.
     

  2. The response k (assignment key guid) is returned when a v5-assigned work unit is registered.
     

  3. <work_unit_token1>=<work_unit_value1> parameters are defined by and must agree with the application-specific parameters.
     

  4. If the assignment belongs to another user's computer or is unavailable, error ERROR_NO_ASSIGNMENT is returned.

5.4.5 APPLICATION-SPECIFIC PARAMETERS

5.4.5.1 GIMPS

5.4.5.1.1 GIMPS Request Parameters

GIMPS-specific application request parameters labeled in 5.4.2.3 above as <work_unit_token1>=<work_unit_value1> token-value pairs are identical to the table of permitted recognized tokens and values in 5.3.5.1.2 GIMPS Response Parameters. Note that kf and saved parameters need not be specified. Parameters A,b,c need not be passed, they default to 1,2,-1 respectively. The sf and p1 parameters need not be sent to register LL work.

5.4.5.1.2 GIMPS Response Parameters

None.

5.4.5.1.3 GIMPS Notes

  1. Request parameter w (work_type) is always required.
     

  2. All request parameters are work_type-dependent and may not necessarily appear in the request transaction parameters.


5.5 au - Assignment Un-reserve

5.5.1 DESCRIPTION

Release a work assignment belonging to this computer and account.

5.5.2 COMMON PARAMETER DATA

5.5.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.5.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=au
&g=3874DFD725BA434082259AA25EA0BE5F
&k=D7259AFD4BA5E5F434082EA0B72538A2
&ss=
&sh=

5.5.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
=END=\n\n

5.5.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
=END=\n\n

5.5.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.5.4 NOTES

  1. Repeatedly getting an assignment and deciding to release it as unfavorable is a discouraged strategy the server will recognize and react by regulating the client program's interaction at a slower transaction rate.
     

  2. k (assignment key) must match k given in a previous 'ra' (register assignment) or 'ga' (get assignment) transaction response.

5.5.5 APPLICATION-SPECIFIC PARAMETERS

None.


5.6 ap - Assignment Progress

5.6.1 DESCRIPTION

Acknowledge a work assignment or report work assignment progress.

5.6.2 COMMON PARAMETER DATA

5.6.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.6.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ap
&g=3874DFD725BA434082259AA25EA0BE5F
&k=D7259AFD4BA5E5F434082EA0B72538A2
&p=11.7
&d=01/17/2003%2013:20:00
&e=01/15/2003%2012:00:00
&s=221221
&r=2
&ss=
&sh=

5.6.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
=END=\n\n

5.6.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
=END=\n\n

5.6.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.6.4 NOTES

  1. This transaction updates the server with work assignment progress information does NOT close an assignment as completed even if p (percent complete) == 100. Programs should send DAILY progress updates of all assignments.
     

  2. Client programs acknowledging a new work assignment must send p = 0 to signal the server work has not started unless work has actually begun. Aggressive parallel progress on a CPU may be interpreted by the server as a spoof or an assignment 'land-grab', resulting in reassignment of the work or invalidation of the program's reported work results.
     

  3. Before a client program starts work on a previously queued/cached assignment, it should send the 'ap' transaction to verify the assignment should still be worked.  If not, ERROR_NO_ASSIGNMENT is returned and the client program should discard the work unit, untested.
     

  4. k (assignment key) must match k given in a previous 'ra' (register assignment) or 'ga' (get assignment) transaction response, and is used to validate the assignment.
     

  5. If the assignment is reported by a different CPU g (GUID) than as originally assigned AND the reporting CPU is bound to the SAME user account, the assignment is updated to reflect transfer of CPU assignment.
     

  6. If the assignment was removed from the server or it currently belongs to a CPU under another user's account, error ERROR_NO_ASSIGNMENT is returned.  Under some circumstances, redundant or supplemental work assignment results may be accepted for credit and no error is returned.

5.6.5 APPLICATION-SPECIFIC PARAMETERS

5.6.5.1 GIMPS

5.6.5.1.1 GIMPS Request Parameters

GIMPS-specific application request parameters labeled in 5.6.2.3 above as <work_unit_token1>=<work_unit_value1> token-value pairs are given in the table of permitted recognized tokens and values below.

work_unit_token
(CASE SENSITIVE)

description

data_type
& constraints

permitted
work_unit_values

Required

FFTK

FFT length in KB for partial CPU credit

integer

 

NO

stage

For multi-stage assignments, the stage currently being run

string

'LL','TFnn' where nn if the TF bit level,
'P-1 1', 'P-1 2', 'ECM 1', 'ECM 2'

NO

5.6.5.1.2 GIMPS Response Parameters

None.

5.6.5.1.3 GIMPS Notes

  1. All other request parameters are work_type-dependent and may not necessarily appear in the transaction URL.


5.7 ar - Assignment Result

5.7.1 DESCRIPTION

Report a work assignment result and optionally close the assignment on the server.

5.7.2 COMMON PARAMETER DATA

5.7.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.7.2.2 Example Request

GIMPS result_type double-check LL primality test result as prime, assignment closed:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ar
&g=3874DFD725BA434082259AA25EA0BE5F
&k=D7259AFD4BA5E5F434082EA0B72538A2
&n=20996011
&r=101
&d=1
&m=M20996011%20is%20prime!%20Res64:%200x000000000000
&ec=00000000
&sc=14345678
&ss=
&sh=

GIMPS result_type trial factoring with factor result, assignment closed:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ar
&g=3874DFD725BA434082259AA25EA0BE5F
&k=D7259AFD4BA5E5F434082EA0B72538A2
&r=1
&d=1
&m=M20996017%20has%20a%20factor:%2073213133123211131271
&f=7321313312321113127
&ss=
&sh=

GIMPS result_type LL first-time primality test with factoring null result to 87 bits, assignment open:

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ar
&g=3874DFD725BA434082259AA25EA0BE5F
&k=D7259AFD4BA5E5F434082EA0B72538A2
&r=4
&d=0
&m=M20996017%20no%20factor%20thru%2087%20bits
&ef=87
&ss=
&sh=

5.7.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
=END=\n\n

5.7.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
=END=\n\n

5.7.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.7.4 NOTES

  1. When d <> 0, the 'ar' transaction closes an assignment as completed and invalidates the assignment key, k.
    When d = 0, the server will expect further results from the client program.
     

  2. Assignments may return more than one result. For example, an exponent may be unsuccessfully trial-factored to 50 bits with d = 0, and then unsuccessfully P-1 factored to 60 bits with d = 0, then LL tested as composite, at which point the assignment is finally closed by setting d > 0.
     

  3. If the assignment is registered to a different CPU g (GUID) than originally assigned AND the reporting CPU is bound to the SAME user account, receipt of the assignment result effects the transfer of the work unit assignment to the reporting CPU.

    If the reported CPU guid is from a different account, ERROR_NO_ASSIGNMENT may be returned. User account credit may be conditional upon the utility of the result. This is called the PrimeNet 'Fair Opportunistic Assignment Result' Policy.
     

  4. When assignment key k=0, no credit is granted. This is called the PrimeNet 'Unexpected Results' Policy.
     

  5. When r = 0, n is optional. Typically used to close an assignment (d <> 0) or log a message.

5.7.5 APPLICATION-SPECIFIC PARAMETERS

5.7.5.1 GIMPS

5.7.5.1.1 GIMPS Request Parameters

GIMPS-specific application request parameters labeled in 5.7.2.3 above as <results_token>=<results_value> token-value pairs are given in the table of permitted recognized tokens and values below.

results_token
(CASE SENSITIVE)

description

data_type
& constraints

permitted
result_values

Required

r

result_type

integer

(see 8.0 GIMPS Result Types)

YES

A

(A*b^n+c)

double

Any positive integer

NO, default is 1

b

(A*b^n+c)

integer

any 32 bit unsigned value

NO, default is 2

n

prime exponent
(A*b^n+c)

integer

any 32 bit unsigned value

YES, except for r=0

c

(A*b^n+c)

integer

any 32 bit signed value

NO, default is -1

B1

P-1/ECM lower bound

double

any positive integer

when r = 2,3,5,6

B2

P-1/ECM upper bound

double

any positive integer

NO

CR

ECM curves run

integer

any 32 bit unsigned value

when r = 6

sf

starting no factor to sf bits

float

0 <= b < 100 (?); sf < ef

when r = 1,4

ef

ending no factor to ef bits

float

0 <= b < 100 (?); ef > sf

when r = 4

f

factor result

hex or decimal-encoded string;
length limit 512 digits;
hex requires leading '0x' prefix

2 <= f < 4^512; length 512

when r = 1,2,3

rd

64bit LL residue

16 digit hex-encoded
character string
NO leading '0x'
; length 18

length 16

when r = 100,101

fftlen

FFT length for calculation proper CPU credit

integer


 

when r = 2,3,5,6,100,101

sc

LL shift count

integer

sc >= 0

when r = 100,101

ec

error counts

8 digit hex-encoded
character string
NO leading '0x'; length 8

length 8

when r = 100,101

5.7.5.1.2 GIMPS Response Parameters

None.

5.7.5.1.3 GIMPS Notes

  1. Request parameter r (result_type) is always required.
     

  2. All other request parameters are result_type-dependent and may not necessarily appear in the transaction URL.


5.8 bd - Benchmark Data Statistics

5.8.1 DESCRIPTION

Report benchmark data statistics for the current CPU and program version.

5.8.2 COMMON PARAMETER DATA

5.8.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.8.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=bd
&g=3874DFD725BA434082259AA25EA0BE5F
&c=over-under-superclocked%20by%GW
&fft384K=34.533
&fft448K=39.939
(... etc., up to 50 timings...)
&ss=
&sh=

5.8.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
=END=\n\n

5.8.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
=END=\n\n

5.8.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.8.4 NOTES

  1. Benchmarks are cumulative and snapshot the current CPU type including L2 cache, clock speed and program version data associated with guid (g) with the benchmark data at the time the benchmark is reported.
     

  2. To ensure the server has the current CPU and application version info when the benchmark is reported, client programs should perform a 'uc' update computer info transaction prior to using the 'bd' benchmark data stats transaction.
     

  3. Up to 50 <timing_token=timing_value> data pairs may be submitted with each benchmark report, subject to an encoded URL query string length < 4096.

5.8.5 APPLICATION-SPECIFIC PARAMETERS

5.8.5.1 GIMPS

5.8.5.1.1 GIMPS Request Parameters

GIMPS-specific application request parameters labeled in 5.8.2.3 above as <timing_token>=<timing_value> token-value pairs are given in the table of permitted recognized tokens and values below.

timing_token

description

data_type
& constraints

permitted
result_values

Required

fft384k

384KB FFT iteration, seconds

float

0 - 500

NO, but at least one of the timing tokens is REQUIRED

fft448k

448KB FFT iteration, seconds

float

0 - 500

NO, but at least one of the timing tokens is REQUIRED

tf64

64-bit trial factoring, seconds

float

0 - 500

NO, but at least one of the timing tokens is REQUIRED

tf65

65-bit trial factoring, seconds

float

0 - 500

NO, but at least one of the timing tokens is REQUIRED

5.8.5.1.2 GIMPS Response Parameters

None.

5.8.5.1.3 GIMPS Notes

None.


5.9 ps - Ping Server

5.9.1 DESCRIPTION

Get a quick server availability & health check, server version or server operating statistics, without referencing account, CPU or assignment information.

5.9.2 COMMON PARAMETER DATA

5.9.2.1 Request Parameters

All common parameters are required and are case-sensitive. Null values are empty strings. Do not use quoted strings.

5.9.2.2 Example Request

http://v5.mersenne.org/v5/
?px=GIMPS
&v=0.97
&t=ps
&q=0
&ss=
&sh=

5.9.2.3 Response TEXT/HTML Parameters

pnErrorResult=<error code>\n
pnErrorDetail=<error message string>\n
r=<query result string>\n
=END=\n\n

5.9.2.4 Example Response

pnErrorResult=0\n
pnErrorDetail=SUCCESS\n
r=PrimeNet Server v5.0.0.97 (GIMPS)\r
(c)1997-2006 Scott Kurowski, Inc. & Just For Fun Software, Inc.\r
primenet@mersenne.org, www.mersenne.org/primenet\n
=END=\n\n

5.9.3 RESPONSE pnErrorResult CODES

Integer error result codes are enumerated in 6.0 API Result Error Codes.

The following may be returned for this transaction:

5.9.4 NOTES

  1. This optional transaction may be issued by a client program to avoid sending account, CPU or assignment-related parameters to determine server availability.
     

  2. Set q (query type) = 0 for a simple server web availability test. Setting q (query type) = 1 performs a full-depth API availability test. Both return a formatted server version string (format TBD) in the r (server response info) parameter.
     

5.8.5 APPLICATION-SPECIFIC PARAMETERS

None.


6.0 PrimeNet API Result Error Codes

Integer error result codes values are enumerated below.

General errors, may be returned for any API transaction:

Account related errors:

Computer cpu/software info related errors:

Work assignment related errors:


7.0 Assignment Work Types

Integer work type values used for ga (Get Assignment), ra (Register Assignment), ap (Assignment Progress), and ar (Assignment Results) API calls.

7.1 System Special Work Types

Assignment work_type=0 is reserved. Assignment work_type values in the range 1024+ are reserved for future system purposes, such as diagnostics, benchmarks, node control or reconfiguration, etc.

7.2 GIMPS Work Types

GIMPS work_type values include the range 0-255:

work_type

work type description

'ga' transaction work_type-specific
response parameters

0-1

reserved future use

 

2

trial factoring

A=1
b=2
n=<exponent> (integer)
c=-1
sf=<no_factor_to_bits> (float)
ef=<factor_to_this_many_bits> (float)

3

P-1 factoring

A=1
b=2
n=<exponent> (integer)
c=-1
B1=<lower_bound> (double)
B2=<upper_bound> (double)
kf=<CSV list of known factors>

4

Optimal P-1 factoring

A=1
b=2
n=<exponent> (integer)
c=-1
sf=<no_factor_to_bits> (float)
saved=<num_LL_tests_saved> (float)

5

ECM factoring

A=1
b=<base> (integer)
n=<exponent> (integer)
c=-1 or c=1
B1=<lower_bound> (double)
B2=<upper_bound> (double)
CR=<curves_run> (integer)
kf=<CSV list of known factors>

8-99

reserved future use

 

100

LL first-time test

A=1
b=2
n=<exponent> (integer)
c=-1
sf=<no_factor_to_bits> (float)
p1=0 or 1

101

LL double-check

A=1
b=2
n=<exponent> (integer)
c=-1
sf=<no_factor_to_bits> (float)
p1=0 or 1

102-255

reserved future use

 

NOTES:

None.

7.3 GIMPS Work Preferences

GIMPS work_type preference values include the range 0-255.

work_type
PREFERENCE

work_type
ASSIGNED

work type description

0

One of work_type in table 7.2 above 

server decides what
makes most sense to assign

1

2

factoring LMH

2

2

factoring trial (sieve)

3

3

factoring P-1 small

4

4

factoring P-1 large

5

5

factoring ECM smallish Mersenne

6

5

factoring Fermat ECM

7

5

factoring Cunningham ECM

8-99

 

reserved future use

100

100

LL first-time test

101

101

LL double-check

102

100

LL test world-record

103

100

LL test 10M digits

104

100

LL test 100M digits

105

100

LL first-time test
with no trial or P-1 factoring

106-255

 

reserved future use

NOTES:

Preference work_type values are saved in the server using the 'po' transaction, and are used to guide assignment selections. The actual work_type assigned will be one of the work_type values in table 7.2.

7.4 Other Work Types

Other work_type values 1024+ are reserved for future use.


8.0 Assignment Result Types

Integer result_type values used for the 'ar' (Assignment Result) API transaction.

8.1 System Special Result Types

Assignment result_type values in the range 1024+ are reserved for future system purposes, such as diagnostics, benchmarks, node control or reconfiguration, etc.

8.2 GIMPS Result Types

GIMPS result_type values include the range 1-256:

result_type

result type description

result_type-specific
'ar' transaction parameters

0

empty result - no result data is expected or recorded by the server; a message may be sent and logged

None.
'ar' parameter n is optional only in this case.

1

factor found (composite) using trial factoring

A=1
b=2
n=<exponent> (integer)
c=-1
f=<factor> (string; max length 200)
sf=<starting bit depth> (float)
ef=<end_bit_depth> (float)

2

factor found (composite) using P-1

A=1
b=2
n=<exponent> (integer)
c=-1
f=<factor> (string; max length 200)
B1=<lower bound> (integer)
B2=<upper bound> (integer, optional)
fftlen=<fft length>

3

factor found (composite) using ECM

A=1
b=2
n=<exponent> (integer)
c=-1
stage=<stage#> (integer)   ?
f=<factor> (string; max length 200)
B1=<lower bound> (integer)
B2=<upper bound> (integer, optional)
fftlen=<fft length>

4

factoring trial (sieve), no factor found

A=1
b=2
n=<exponent> (integer)
c=-1
sf=<starting bit depth> (float or integer)
ef=<ending bit depth> (float or integer)

5

factoring P-1, no factor found

A=1
b=2
n=<exponent> (integer)
c=-1
B1=<lower_bound> (integer)
B2=<upper_bound> (integer) (optional)
fftlen=<fft length>

6

factoring ECM, no factor found

A=1
b=2
n=<exponent> (integer)
c=-1 or c=1
B1=<lower_bound> (integer)
B2=<upper_bound> (integer)
CR=<curves_run> (integer)
fftlen=<fft length>

7-99

factoring results reserved

 

100

LL residue (composite)

A=1
b=2
n=<exponent> (integer)
c=-1
rd=<64-bit hex residue digits> (string; length 16)
sc=<shift count> (integer)
ec=<error_count> (string; length 8)
fftlen=<fft length>

101

LL residue (prime!)

A=1
b=2
n=<exponent> (integer)
c=-1
sc=<shift count> (integer)
ec=<error_count> (string; length 8)
fftlen=<fft length>

NOTES:

None. 

8.3 Other Result Types

Other result_type values 1024+ are reserved for future use.